Getting started with the Shopify GitHub integration

The Shopify GitHub integration lets you make and track changes to theme code using Git. This tutorial explains how to install the Shopify Online Store GitHub app, connect a branch as a theme, test the connection, and then publish the theme.

Before you start

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.

Step 1: Connect to a GitHub organization or account

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 Online Store 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 the Shopify Online Store GitHub app access to GitHub repositories.

Step 2: Connect a branch as a theme

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.

  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.

Step 3: Test the connection

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-online-store app and your username as the authors of the commit.

A commit from Shopify in the GitHub repo

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.

The card for a theme that's connected to GitHub

Step 4: Publish 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.