Hydrogen supports CI/CD with GitHub out of the box. If you connect the [Hydrogen channel](/docs/storefronts/headless/hydrogen/fundamentals#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:

- [Connect an existing Hydrogen app repository](#connect-an-existing-repo)
- [Scaffold a new repository from the Shopify admin](#create-a-new-repo)

## Requirements

- A Shopify account on a [supported plan](/docs/storefronts/headless/hydrogen/fundamentals#supported-plans).
- A GitHub account.
- The [Hydrogen app](https://apps.shopify.com/hydrogen) installed on your store.
- The [Shopify GitHub App](https://github.com/marketplace/shopify-online-store/) installed on your GitHub account.

## Connect an existing repo

If you created a [Hydrogen app with the CLI](/docs/storefronts/headless/hydrogen/getting-started), then you can [upload your repository to GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git) and then connect it to Shopify.

### Step 1: Connect your GitHub repo to the Hydrogen channel

1. In the Shopify admin, under **Sales channels**, click **Hydrogen**.
1. Click **Create storefront**.
1. Type a name for your new storefront. The name can be edited later.
1. Make sure **Set up GitHub continuous deployment now** is selected.
1. Select your GitHub account or organization from the dropdown.
1. Select the repository for your Hydrogen app.
1. 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.

### Step 2: Merge your Oxygen workflow file

To create deployments, Oxygen requires a [GitHub workflow file](#oxygen-github-workflow) 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](/assets/custom-storefronts/hydrogen/oxygen-pr.png)

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.
1. Click **Review and merge on GitHub** to open the pull request in a new tab.
1. Follow GitHub’s prompts to [merge the PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request).
1. 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.

## Create 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**.
1. Click **Create storefront**.
1. Type a name for your new storefront. The name can be edited later.
1. Make sure **Set up GitHub continuous deployment now** is selected.
1. Select your GitHub account or organization from the dropdown.
1. Type a name for the new repository.
1. Click **Create \<repository name\>**.
1. (Optional) If you want the repository to be public, then click **Create \<repository name\> as a public repository**.
1. Select **JavaScript** or **TypeScript** for your project language.
1. 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.

## Enable 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**.
1. Click **Oxygen deployments**.
1. Under **Git repository**, check **Comment on pull requests with deployment preview links**.
1. (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](/docs/storefronts/headless/hydrogen/deployments#shareable-links).

To test that comments are working, [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for your Hydrogen app. The Shopify GitHub bot adds a comment, then updates it with more details as the deployment proceeds.

## Oxygen GitHub workflow

Deployments to Oxygen from GitHub are controlled by an Oxygen workflow file in your Hydrogen app. If you [connected an existing repo](#connect-an-existing-repo), then Shopify will automatically [open a PR](#step-2-merge-your-oxygen-workflow-file) to add this file when you connect a repository. If you [created a new repo](#create-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:

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="filename" data-value="/.github/workflows/oxygen-deployment-0000000000.yml"></script>

<script type="text/plain" data-language="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 }}

</script>

</div>
</p>


This is a standard [GitHub Actions](https://docs.github.com/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](#alternate-package-managers), 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](https://github.com/Shopify/hydrogen-demo-store/blob/main/.github/workflows/oxygen-deployment-1000013955.yml).

### Alternate package managers

If you're using a package manager other than npm, such as [Yarn](https://yarnpkg.com/) or [pnpm](https://pnpm.io/), note the following:

- Hydrogen and Oxygen use npm by default. Shopify can’t guarantee compatibility with other package managers.
- The [Oxygen deployment workflow file](#oxygen-github-workflow) 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.

## Next steps

- Support other version control platforms or more complex deployment systems with [custom CI/CD workflows](/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd).
- Learn more about creating and managing Hydrogen [environments](/docs/storefronts/headless/hydrogen/environments)