Hydrogen CI/CD with GitHub

• A Shopify account on a supported plan.
• A GitHub account.
• The Hydrogen app installed on your store.
• The Shopify GitHub App installed on your GitHub account.

If you created a Hydrogen app with the CLI, then you can upload your repository to GitHub and then connect it to Shopify.

1. In the Shopify admin, under Sales channels, click Hydrogen.
2. Click Create storefront.
3. Type a name for your new storefront. The name can be edited later.
4. Make sure Set up GitHub continuous deployment now is selected.
5. Select your GitHub account or organization from the dropdown.
6. Select the repository for your Hydrogen app.
7. Click Connect.

Oxygen pulls a copy of your Hydrogen app code base and automatically creates a preview deployment. The Shopify GitHub app also opens a pull request in your repo to add a GitHub Actions workflow file to handle future deployments.

To create deployments, Oxygen requires a GitHub workflow file in your repository. The Shopify GitHub app automatically opens a pull request to create this file when you connect a repo:

Follow these steps to finish configuring your Hydrogen app for continuous deployment to Oxygen:

1. In the Hydrogen channel, click the name of the storefront that you just created.
2. Click Review and merge on GitHub to open the pull request in a new tab.
3. Follow GitHub’s prompts to merge the PR.
4. Close the tab to return to the Hydrogen storefront overview.

Oxygen will automatically create a new deployment in your production environment and continue watching your repo for updates. Each time you push one or more commits to your repo, Oxygen will create a new preview deployment with your changes.

You can create a new Hydrogen storefront and scaffold a new GitHub repository directly from the Shopify admin:

1. In the Shopify admin, under Sales channels, click Hydrogen.
2. Click Create storefront.
3. Type a name for your new storefront. The name can be edited later.
4. Make sure Set up GitHub continuous deployment now is selected.
5. Select your GitHub account or organization from the dropdown.
6. Type a name for the new repository.
7. Click Create <repository name>.
8. (Optional) If you want the repository to be public, then click Create <repository name> as a public repository.
9. Select JavaScript or TypeScript for your project language.
10. Click Create.

Shopify scaffolds a new Hydrogen app in your GitHub account, displays the storefront overview page, and automatically creates the first deployment of your storefront. Clone the new repo to start working on your Hydrogen app.

You can configure Shopify to comment on your pull requests with deployment preview links. This allows you to quickly access deployments in context, without needing to open the Shopify admin.

To enable deployment PR comments on GitHub:

1. In your Hydrogen storefront, click Storefront settings.
2. Click Oxygen deployments.
3. Under Git repository, check Comment on pull requests with deployment preview links.
4. (Optional) If you want preview links to be visible without needing to be logged into your store, select Anyone with the link. This option uses shareable links.

To test that comments are working, create a pull request for your Hydrogen app. The Shopify GitHub bot adds a comment, then updates it with more details as the deployment proceeds.

Deployments to Oxygen from GitHub are controlled by an Oxygen workflow file in your Hydrogen app. If you connected an existing repo, then Shopify will automatically open a PR to add this file when you connect a repository. If you created a new repo from the Shopify admin, then this file was automatically added.

This is an example of what an Oxygen workflow file looks like:

This is a standard GitHub Actions workflow file and you can edit it to customize your CI/CD workflows in GitHub. However, there are few key points to be aware of:

• Don't change the line below! refers to the immediate line following, which contains the app's associated storefront ID.
• By default, the workflow installs app dependencies with npm. If you use a different package manager, then you’ll need to edit this file to prevent errors caused by multiple lockfiles, as well as to manage module caching.

Refer to a live example on our Hydrogen demo store.

If you're using a package manager other than npm, such as Yarn or pnpm, note the following:

• Hydrogen and Oxygen use npm by default. Shopify can’t guarantee compatibility with other package managers.
• The Oxygen deployment workflow file uses npm by default, and assumes the presence of a package-lock.json file. You can edit the workflow file to use your preferred package manager. In particular, check that the steps to install dependencies, cache modules, and build your app are updated to use the correct commands.

• Support other version control platforms or more complex deployment systems with custom CI/CD workflows.
• Learn more about creating and managing Hydrogen environments