Shopify GitHub integration

The Shopify GitHub integration lets you associate a GitHub account with your Shopify login, and then connect Git repositories to themes in your Shopify admin. This connection helps you to make and track changes to theme code. It also helps you to collaborate with other developers and share progress in real time.

Features

The Shopify GitHub integration includes the following features:

  • Automatically pull and push theme code from any organization or repository associated with your GitHub account
  • Connect one or more branches from a repository to easily develop and test new theme features or campaigns
  • Keep a theme up to date with commits to a branch, and track edits made in the Shopify admin, including the code editor and theme editor
  • Connect branches to unpublished or published themes

How it works

The Shopify GitHub integration updates your theme in the Shopify admin whenever the connected branch is updated. It also commits changes made through the Shopify admin to the branch to ensure that the branch and theme in the admin always match.

Commits by Shopify

When your theme is edited through the Shopify admin, any changes are automatically committed to your repository by Shopify. A commit is created when any owner, staff member, or collaborator makes changes. Changes are added as a commit to the connected branch when they are saved.

You can edit your theme in the following areas of the Shopify admin:

Connection to GitHub

Only repositories that are connected to a theme are visible to other users in the store. After a branch is connected to a theme, any user who has the Themes permission can disconnect it.

You can connect only one GitHub account to your Shopify login.

To set up your connection to GitHub, you need to log into the store directly using an owner or staff member account. Make sure that you log in using the store URL (for example, my-example-store.myshopify.com/admin) instead of logging in through the Partner Dashboard.

After you connect your Shopify admin to your account or repository, only your staff account can do the following:

  • Connect repositories and branches that you have access to
  • Disconnect your GitHub account from Shopify

If multiple staff members need to manage connections to a repository, then each staff member needs to set up the Shopify GitHub integration on their own staff account.

If you want to completely disconnect your GitHub account or organization from the Shopify store, then you need to uninstall the Shopify GitHub app through GitHub.

Conflicts and error handling

If a user has a file open and is editing it in the theme editor, and then the same file is edited in GitHub or the code editor, then the user is warned that they are overriding the new changes when they save.

There are currently no conflict alerts in the code editor. The version of the file in the code editor overwrites the GitHub version of the file.

In case of a conflict in commits or pushes made outside Shopify, the developer has a chance to resolve it in GitHub or force push the change to overwrite the file in Shopify.

In limited cases, conflicts might occur if a file is saved in the theme editor or code editor and a change is pushed to the GitHub branch simultaneously. In this case, the commit coming from Shopify might be viewed as outdated and rejected by GitHub.

If you suspect that an error has occurred when pushing or pulling changes, then you can view the logs for the last few version control events by clicking View logs beside the Last saved timestamp on the theme card.

If you believe that the theme has fallen out of date with the branch, then you can pull the latest version of the branch manually by going to the theme card and selecting Actions > Reset to last commit.

Getting started

To learn how to connect your account or organization to GitHub and connect a branch as a theme, refer to Getting started with the Shopify GitHub integration.

Repository structure

You can connect only branches that match the default Shopify theme folder structure. This structure represents a buildless theme, or a theme that has already gone through any necessary file transformations.

The .github folder in your repository is ignored. As a result, you can still use task automation and continuous integration tools, such as Lighthouse CI, by using this method.

If you want to use the Shopify GitHub integration with a theme that uses a build pipeline, then you can separate your source and generated code into two separate repositories, or store your generated code as a subtree or submodule, which you can then connect to a Shopify theme. You can also use these approaches to prevent Shopify from making changes to source code that follows the default folder structure.

Using these models, you need to backfill changes that are made to your generated code by Shopify into your source code. To learn more about these approaches to version control, refer to our version control best practices.

Branch management strategies

Consider the following when managing themes connected to GitHub repositories in Shopify:

  • You can't reconnect a branch to a theme after it has been disconnected. If you reconnect a branch, then it's added as a new theme.

  • If an unpublished theme is connected to a branch and then published, then it maintains its connection to the branch.

To understand the relationship between branches and themes, and how to optimize your workflow to use branches effectively, refer to our version control best practices.