Integrating GitHub with Your Shopify Store

Shopify’s theme editor works well for small changes, but theme management becomes more demanding when several developers, campaigns, and releases are involved.

Files downloaded as ZIP archives quickly become outdated. Duplicate themes are difficult to compare, and edits made directly in Shopify can overwrite another developer’s work. Without a shared version history, teams may not know what changed, who changed it, or which version is safe to publish.

Shopify’s GitHub integration introduces a more controlled workflow. It synchronizes a Shopify theme with a GitHub branch, records theme changes as commits, and allows developers to use branches and pull requests before updating the connected theme.

This guide explains how the integration works, how to connect an existing Shopify theme, and how to create a development workflow that does not put the live store at unnecessary risk.

What Does the Shopify GitHub Integration Do?

The Shopify GitHub app connects a branch in a GitHub repository to a theme in Shopify.

The synchronization is bidirectional:

• When a developer pushes a commit to the connected branch, Shopify updates the connected theme.
• When someone edits the connected theme through Shopify admin, Shopify commits those changes back to the branch.

Admin changes can originate from:

• The Shopify theme editor
• Shopify’s code editor
• Theme applications that modify connected theme files

This is an important difference from a traditional one-way deployment pipeline. The GitHub repository is not automatically the only place where changes can originate. If merchants or staff continue editing the connected theme in Shopify, those changes become part of the repository history.

A connected theme card displays its repository, branch, and most recent commit. Shopify also provides synchronization logs for investigating failed or delayed updates.

Why Connect Shopify to GitHub?

Complete Change History

Every commit records which files changed and when the change was made. Teams can compare versions instead of trying to identify differences between downloaded theme archives.

Safer Collaboration

Each developer can work on a separate branch. Pull requests provide a place to review the code, discuss implementation details, run automated checks, and resolve conflicts before merging.

Easier Rollbacks

If a deployment creates a problem, the relevant commit can be reverted in GitHub. Once the revert reaches the connected branch, Shopify synchronizes the earlier code back to the theme.

Better Release Control

Features can be developed and tested in isolation before they reach the production branch. This is useful for:

• New theme sections
• Navigation changes
• Seasonal campaigns
• Product-page redesigns
• Performance improvements
• Analytics updates
• Accessibility fixes

Visibility Into Shopify Admin Changes

The integration records changes saved through the connected Shopify theme. This helps developers see when a merchant, collaborator, application, or staff member modifies theme files or settings.

However, a commit explains what changed, not necessarily why it changed. Teams should still document significant admin edits and avoid making unplanned changes directly to production.

How Shopify Themes, Branches, and GitHub Relate

A Shopify theme can be connected to one repository branch. Different branches can be connected as separate themes in the Shopify theme library.

A practical relationship looks like this:

Only one Shopify theme can be published at a time, but multiple connected themes can exist in the theme library.

If a connected unpublished theme is later published, it retains its GitHub connection. Future commits to that branch will therefore update the published theme.

This means merging into a branch connected to the live theme is effectively a production deployment.

Prerequisites

Before starting, make sure you have:

• Access to the Shopify store
• The necessary Shopify theme permissions
• A GitHub account
• A GitHub repository you own or can write to
• A valid Shopify theme structure
• A backup or duplicate of the current theme
• Shopify CLI if you plan to develop locally

For GitHub organizations, repository visibility and connection permissions depend on both the Shopify permissions and GitHub access granted to the Shopify app.

Grant the Shopify GitHub app access only to repositories the store genuinely needs.

Required Shopify Theme Structure

Shopify can connect only to branches containing its supported theme directory structure.

A typical repository root looks like this:

shopify-theme/
├── assets/
├── blocks/
├── config/
├── layout/
├── locales/
├── sections/
├── snippets/
└── templates/

Not every theme needs every optional directory, but the theme files must be available at the repository root in a format Shopify can use.

A branch containing only source files such as the following cannot be connected directly:

src/
dist/
webpack.config.js
package.json

If the project uses Sass, TypeScript, Webpack, Vite, Rollup, PostCSS, or another build process, the branch connected to Shopify must contain the compiled Shopify-compatible theme.

Shopify recommends separating source and deployable code through branches or repositories when a build process is involved.

Step 1: Create the GitHub Repository

In GitHub:

1. Click New repository.
2. Enter a descriptive name, such as store-name-theme.
3. Choose whether it should be private or public.
4. Avoid adding unrelated application or backend code.
5. Create the repository.

A private repository is normally the safer choice for a custom commercial theme. Repository visibility does not replace proper secret management, but it reduces unnecessary exposure of proprietary theme code.

Step 2: Export the Existing Shopify Theme

There are two practical ways to bring an existing theme into GitHub.

Option A: Download the Theme ZIP

This method is suitable for merchants who are not yet using Shopify CLI.

1. In Shopify admin, go to Online Store > Themes.
2. Find the theme you want to place under version control.
3. Open its actions menu.
4. Select Download theme file.
5. Download the ZIP from the email sent by Shopify.
6. Extract the archive.
7. Confirm that the theme folders remain at the repository root.

Do not place the extracted theme inside an additional nested folder before connecting it.

Option B: Pull the Theme With Shopify CLI

Developers can use Shopify CLI to pull theme files directly:

shopify theme pull --store your-store.myshopify.com

Shopify will prompt you to select the theme when one is not specified.

Run the command from an empty project directory and verify the downloaded files before committing them.

Shopify CLI is generally more convenient for ongoing local development because it also supports development themes, preview links, and hot reloading.

Step 3: Commit and Push the Theme

From the theme directory, initialize Git and push the first version:

git init
git add .
git commit -m "Add existing Shopify theme"
git branch -M main
git remote add origin https://github.com/your-account/your-repository.git
git push -u origin main

Before committing, review the repository for credentials or files unrelated to the theme.

Never commit:

• Shopify access tokens
• GitHub tokens
• Private keys
• .env files
• Third-party API secrets
• Customer exports
• Order or payment data

Theme JavaScript must not contain private API credentials. Any value delivered to the browser should be treated as publicly visible, whether GitHub is private or not.

Step 4: Install and Authorize the Shopify GitHub App

In Shopify:

1. Go to Online Store > Themes.
2. Find the Theme library.
3. Click Add theme.
4. Select Connect from GitHub.
5. Sign in to GitHub when prompted.
6. Select your GitHub account or organization.
7. Grant access to the required repository.
8. Complete the installation.

When possible, choose Only select repositories instead of granting access to every repository in the account or organization.

If a required repository is created later, return to the GitHub app settings and grant Shopify access to it.

Step 5: Connect the Repository and Branch

From the connection panel:

1. Choose the GitHub organization or account.
2. Select the theme repository.
3. Select the branch to connect.
4. Confirm the connection.

Shopify adds the branch as a theme in the theme library. It does not need to become the live theme immediately.

The connected theme card should display:

• Repository name
• Branch name
• Latest commit
• Synchronization status
• Version-control logs

At this point, keep the theme unpublished while you test the integration.

Step 6: Test Two-Way Synchronization

Test changes in both directions before publishing the connected theme.

Test GitHub to Shopify

1. Create a small change locally.
2. Commit it.
3. Push it to the connected branch.
4. Open the connected Shopify theme.
5. Confirm that the change appears.
6. Review the synchronization logs.

For example:

git add .
git commit -m "Update announcement bar styling"
git push origin main

Test Shopify to GitHub

1. Open the connected theme in Shopify’s theme editor.
2. Change a harmless setting, such as announcement-bar text.
3. Save the theme.
4. Open the GitHub repository.
5. Confirm that Shopify created a commit.

The commit should identify the Shopify bot as its author.

Shopify automatically commits admin changes to connected branches. This behaviour cannot be disabled for an individual connected theme.

Step 7: Preview and Publish the Connected Theme

Test the connected theme before publishing it.

Review:

• Homepage sections
• Product pages
• Collection templates
• Search
• Navigation
• Cart behaviour
• Customer accounts
• App blocks
• Languages and markets
• Analytics
• Mobile layouts
• Accessibility
• Core Web Vitals
• Checkout entry points

When the connected theme has been approved, publish it from the Shopify theme library.

Once published, commits pushed or merged into its connected branch can update the live storefront automatically. Restrict who can merge into that branch and treat every merge as a production deployment.

Recommended Shopify GitHub Workflow

A reliable team workflow separates development, review, testing, and production.

1. Start With an Updated Local Branch

git switch main
git pull origin main

Pulling before starting reduces the chance of working from outdated theme files, including changes Shopify may have committed from the admin.

2. Create a Feature Branch

git switch -c feature/product-size-guide

Use descriptive branch names such as:

feature/predictive-search
fix/mobile-cart-drawer
performance/product-image-lcp
campaign/summer-sale

3. Develop Locally With Shopify CLI

Run:

shopify theme dev --store your-store.myshopify.com

Shopify CLI creates or updates a development theme and provides:

• A local preview
• Hot reloading
• A theme editor link
• A shareable preview link

This is why GitHub integration does not replace Shopify CLI. GitHub manages versions and synchronization, while Shopify CLI improves local development and testing.

4. Run Theme Check

Before committing, validate the theme:

shopify theme check

Theme Check can identify Liquid errors, deprecated patterns, missing templates, and several performance or maintainability issues.

Automated checks should support human review rather than replace it. A technically valid theme can still contain broken interactions or poor mobile usability.

5. Commit the Change

git add .
git commit -m "Add accessible product size guide"
git push -u origin feature/product-size-guide

Keep commits focused. A pull request containing one clear feature is easier to review and revert than a large collection of unrelated changes.

6. Open a Pull Request

The reviewer should check:

• Liquid logic
• JavaScript behaviour
• Responsive styling
• Accessibility
• Theme editor compatibility
• Performance impact
• App compatibility
• Translation handling
• Analytics events
• Cart and product functionality

Use screenshots or a preview link to show the visual result.

7. Test in an Unpublished Theme

For high-risk changes, connect a staging branch to an unpublished Shopify theme or push the branch through Shopify CLI.

Test using realistic products, variants, discounts, markets, customer states, and devices.

8. Merge Into the Production Branch

After approval, merge the pull request into the branch connected to the production theme.

Shopify detects the new commit and applies it to the connected theme.

If that theme is published, the merged code can affect customers immediately. Schedule high-risk releases and keep a rollback plan ready.

A Note About Branch Protection

GitHub branch protection can require pull requests, reviews, and status checks before developers merge into the production branch.

However, remember that Shopify also commits admin changes directly to the connected branch. Protection rules or repository restrictions that prevent the Shopify app from writing may interfere with bidirectional synchronization.

Choose one of these operating models:

Developer-Controlled Production

Developers make code changes through GitHub, while merchants avoid editing the connected live theme directly. Theme customizations are made in a connected staging theme and promoted through the agreed workflow.

Shared Admin and GitHub Editing

Merchants can use Shopify’s theme editor, and Shopify commits those changes to the branch. Developers must pull frequently and account for Shopify-generated commits before opening or merging pull requests.

The second approach is more flexible but requires stronger team communication.

Handling Merge and Synchronization Conflicts

Conflicts can happen when the same file is changed in GitHub and Shopify at nearly the same time.

For example, a developer may modify config/settings_data.json while a merchant saves changes through the theme editor.

Shopify documents several important behaviours:

• The theme editor may warn a user before overwriting newer changes.
• Shopify’s code editor does not always provide a conflict warning.
• A code-editor save can overwrite the GitHub version.
• A Shopify-generated commit may be rejected if the branch changed simultaneously.
• External Git conflicts must be resolved in GitHub.

When a synchronization problem occurs:

1. Stop making additional edits.
2. Open the theme card in Shopify.
3. Select View logs.
4. Identify the failed push or pull.
5. Compare the relevant GitHub commits.
6. Resolve the conflict in a separate branch.
7. Test the corrected version.
8. Merge or push the resolution.

If the theme has fallen behind its branch, Shopify provides Actions > Reset to last commit on the connected theme.

Use that option carefully because it resets the Shopify theme to the branch’s latest commit and can overwrite unsynchronized admin changes.

How to Roll Back a Shopify Theme Deployment

Git makes rollback more controlled, but a rollback should still be tested.

Revert the Problematic Commit

git revert COMMIT_HASH
git push origin main

git revert creates a new commit that reverses the earlier change while preserving the repository history.

This is generally safer than rewriting production history with a force push.

Revert a Merged Pull Request

GitHub can create a revert pull request for an eligible merged pull request. Review and test that revert before merging it into the production branch.

Restore a Known-Good Release

For larger problems, create a release branch from a known-good commit, connect or test it as an unpublished theme, and publish it after verification.

Avoid using git reset --hard and force-pushing to a shared production branch unless the team fully understands the consequences. Rewriting history can disrupt other developers and Shopify’s synchronization state.

Source Code and Compiled Theme Files

Some Shopify themes use development tools that transform source files before Shopify can use them.

For example:

Source:
src/scripts/theme.ts
src/styles/theme.scss

Compiled:
assets/theme.js
assets/theme.css

Shopify’s GitHub integration needs a branch that contains the compiled theme in Shopify’s expected folder structure.

A practical arrangement is:

A CI workflow can test and build the source, then update the deploy branch after approval.

This prevents development-only folders from becoming mixed with the production theme while retaining a record of the files delivered to Shopify.

Security and Permission Best Practices

Limit Repository Access

Grant developers only the GitHub permissions required for their roles. Not every contributor needs permission to merge into production.

Restrict the Shopify GitHub App

Authorize only the repositories that Shopify must access. Giving access to every organizational repository unnecessarily expands visibility.

Protect Production Branches

Require pull requests, reviews, and automated checks where they do not prevent Shopify’s required synchronization behaviour.

Protect Shopify Theme Permissions

Only trusted users should be able to publish themes, edit code, manage themes, or connect repositories.

Never Store Secrets in Theme Files

Shopify themes run in the customer’s browser. Private keys, Admin API tokens, and third-party secrets must remain in a secure server-side environment.

Review Third-Party Changes

Theme apps can modify connected theme files. Review Shopify-generated commits and investigate unexpected changes before merging further work.

Important Limitations

Shopify’s GitHub integration is designed specifically for theme files, not the complete store.

It does not version-control:

• Products
• Orders
• Customers
• Discounts
• Navigation data
• Store settings outside the theme
• Application databases
• Checkout configuration
• Metafield values
• Files stored outside the theme repository

It also has repository limitations:

• You need write access to connect a branch.
• Personal repositories where you are only a collaborator might not appear.
• Outside collaborators cannot connect organization branches.
• The branch must match Shopify’s theme structure.
• Files outside the supported theme structure are ignored.
• A disconnected branch cannot simply be reattached to the same theme; reconnecting creates a new theme.

GitHub provides version control for theme code, not a complete Shopify backup.

Does GitHub Replace Shopify CLI?

No. They solve related but different problems.

A strong development workflow normally uses both.

GitHub controls the history, review, and release process. Shopify CLI gives developers a faster and safer environment for building and previewing changes.

Frequently Asked Questions

Why should I connect GitHub to Shopify?

GitHub provides detailed version history, branches, pull requests, code review, and controlled rollbacks. Shopify’s integration also records changes made through the connected theme editor and code editor as repository commits.

Does Shopify automatically deploy changes from GitHub?

Yes. A commit pushed or merged into a connected branch updates its Shopify theme automatically. If that theme is currently published, the change can affect the live storefront without another manual deployment.

Does Shopify sync theme changes back to GitHub?

Yes. Changes saved through Shopify’s theme editor, code editor, or certain theme applications are committed to the connected branch by Shopify, keeping the repository and connected theme synchronized in both directions.

Can multiple developers work on a Shopify theme safely?

Yes. Developers should use separate feature branches, local previews, Theme Check, pull requests, and code reviews. Only tested and approved work should be merged into the branch connected to production.

Is the Shopify GitHub integration secure?

Shopify uses its GitHub application to access authorized repositories. Limit access to selected repositories, control production merge permissions, review Shopify-generated commits, and never place private credentials or customer data in theme files.

Do I still need Shopify CLI after connecting GitHub?

Usually, yes. GitHub manages version control and branch synchronization, while Shopify CLI provides local development, hot reloading, development themes, preview links, theme pulling, pushing, and automated Theme Check validation.

Can GitHub back up my complete Shopify store?

No. The integration versions theme files only. It does not back up products, orders, customers, discounts, application data, metafield values, store settings, or other information stored outside the connected theme.

How do I undo a broken Shopify theme deployment?

Revert the relevant Git commit, test the reversal, and push it to the connected branch. Shopify then synchronizes that version. Avoid force-pushing shared production branches unless absolutely necessary.

Conclusion

Integrating GitHub with Shopify creates a traceable and collaborative theme-development workflow.

The integration synchronizes changes in both directions: commits update the connected Shopify theme, while changes saved through Shopify admin are committed back to GitHub. This gives developers and merchants a shared record of theme activity.

The safest implementation connects an unpublished theme first, verifies synchronization, and publishes only after testing. From there, developers should use Shopify CLI for local development, feature branches for isolated work, pull requests for review, and a controlled production branch for releases.

GitHub does not eliminate every deployment risk or replace a complete Shopify backup. It provides the structure needed to understand changes, collaborate safely, and recover from theme-code problems more efficiently.

Stores requiring a more advanced deployment pipeline, custom build process, or multi-developer workflow can work with experienced Shopify experts to design a process appropriate for the store’s release frequency and risk.