Skip to main content

Hydrogen CI/CD with GitHub

Hydrogen supports CI/CD with GitHub out of the box. If you connect the Hydrogen channel to GitHub, then Oxygen will automatically deploy every time you push or merge changes in your Hydrogen repository.

When using Hydrogen with GitHub, you have two options:

Anchor to RequirementsRequirements

Anchor to Connect an existing repoConnect an existing repo

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

Anchor to Step 1: Connect your GitHub repo to the Hydrogen channelStep 1: Connect your GitHub repo to the Hydrogen channel

  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.

Anchor to Step 2: Merge your Oxygen workflow fileStep 2: Merge your Oxygen workflow file

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:

Hydrogen storefront overview page with an alert banner asking to review and merge a pull request on GitHub

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.

Anchor to Create a new repoCreate a new repo

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.

Anchor to Enable deployment PR commentsEnable deployment PR comments

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.

Anchor to Oxygen GitHub workflowOxygen GitHub workflow

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:

/.github/workflows/oxygen-deployment-0000000000.yml

# Don't change the line below!
#! oxygen_storefront_id: 0000000000

name: Storefront 0000000000
on: [push]

permissions:
contents: read
deployments: write

jobs:
deploy:
name: Deploy to Oxygen
timeout-minutes: 30
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Setup node.js
uses: actions/setup-node@v4
with:
node-version: 'lts/*'
check-latest: true

- name: Cache node modules
id: cache-npm
uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
path: ~/.npm
key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-build-${{ env.cache-name }}-
${{ runner.os }}-build-
${{ runner.os }}-

- name: Install dependencies
run: npm ci

- name: Build and Publish to Oxygen
run: npx shopify hydrogen deploy
env:
SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_0000000000 }}

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.

Anchor to Alternate package managersAlternate package managers

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.

Anchor to Next stepsNext steps

Was this page helpful?