Getting started with the Shopify GitHub integration

Before you start using the Shopify GitHub integration, do the following:

• If you want to use a development store to build a theme, then create or log in to a Shopify Partner account, and then create a development store.
• Make sure that you have an account with the Manage themes permission or Themes permission for the store that you want to work on, or that you're the owner of the store.

• Note the GitHub repository and branch that you want to connect to. The branch must match the default Shopify theme folder structure. You can't create a repository or branch from a theme in the Shopify admin.

  • If you don't have a theme yet, then consider initializing one with Shopify CLI.
  • If you want to use an existing theme from your store, then you can download a ZIP of the theme and then create a repository with its contents.
  • If the repository belongs to an organization where you don't have rights to install an app, then you need to request that your administrator approve the installation before you can connect a theme. You can also request that your administrator install the app for your organization.

To get started with the Shopify GitHub integration, you need to connect a GitHub organization or account to Shopify.

If you're using a new development store, then you can't set up the GitHub integration on the initial login after the store is created. To connect to GitHub successfully, you need to log out of the store, then log in to it again through the Partner Dashboard.

1. From your Shopify admin, go to Online Store > Themes.
2. In the Theme library section, click Add theme > Connect from GitHub.
3. In the Connect theme pane, click Log in to GitHub.
4. Enter your GitHub credentials.
5. You're prompted to authorize and install the Shopify GitHub app. Select whether you want to install the app on your personal account or for your organization.
6. If you're installing the app for an organization, then choose whether to install the app for all repositories, or select repositories. Shopify recommends only granting access to specific repositories that you want to use with this integration. Learn more about granting Shopify access to GitHub repositories.

To connect a branch to a theme in the Shopify admin, you need to choose a branch. The contents of the branch are added as a new theme in your theme library.

Branches that are 50 MB or larger can't be connected to Shopify.

1. From your Shopify admin, go to Online Store > Themes.
2. In the Theme library section, click Add theme > Connect from GitHub.
3. If prompted, log into GitHub.
4. If you're connecting a repository that belongs to an organization, then select the organization that the repository belongs to.
5. Select the repository that you want to connect, and then select the branch that you want to connect.

The theme appears in your theme library. Themes that are connected to GitHub list the repository, branch name, and last commit time on the theme card.

After the initial connection is made, all commits to the branch that you selected are pulled into the theme, and all changes that you make through the Shopify admin are pushed to the branch.

To ensure that the connection between your branch and repository is working, you can make a small change to the theme and then verify that a commit was made in the branch.

1. From your Shopify admin, go to Online Store > Themes.
2. On the theme that's connected to GitHub, click Customize.
3. Change any setting in your theme. For example, in Dawn, you might change the text on the announcement bar.
4. Click Save, and then exit the theme editor.
5. In the theme library, on the card for the theme, click the name of the branch to navigate to GitHub.
6. Note the most recent commit. It should list the shopify bot as the author of the commit.

If desired, you can also push a change to the branch from your local machine. After you push a commit to your branch, the Last saved date on the theme updates and the change is visible in the theme.

To track changes to your published theme, you need to publish a theme from your theme library that's connected to a GitHub branch. You might add your master or main branch as a theme so you can keep your published theme up to date using Git branching and merging strategies. Learn more about branching strategies for themes.

You can publish the theme manually through the Shopify admin, or through Shopify CLI.

In rare circumstances, when you have SSO enabled on your organization, the connection to your GitHub account might fail but show a successful connection. To rebuild the connection, you can revoke the Shopify GitHub app's access to your account through your GitHub settings, and then ensure that you're logged in and have an active SAML session before completing the setup process again.

You can create a SAML session by visiting https://github.com/orgs/ORGANIZATION-NAME/sso in your browser. Replace ORGANIZATION-NAME with the name of your organization.

For more information about SAML authentication, refer to the GitHub documentation.