--- title: Deploy from any CI/CD system with deployment tokens description: >- Learn how to use Oxygen deployment tokens to create deployments with any CI/CD system. source_url: html: >- https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/deployments/custom-ci-cd md: >- https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/deployments/custom-ci-cd.md api_name: hydrogen --- Legacy Hydrogen These pages refer to Hydrogen versions 2026-04 and earlier. For versions 2026-10 and later, refer to the latest [Hydrogen docs](https://shopify.dev/docs/storefronts/hydrogen). If you're not using the latest version of Hydrogen, then we recommend that you migrate your storefront. To learn more, refer to [Migrate to the latest version of Hydrogen](https://shopify.dev/docs/storefronts/hydrogen/migrate). # Deploy from any CI/CD system with deployment tokens Hydrogen supports [continuous deployment from GitHub](https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/deployments/github) out of the box. But if you use another version control platform like BitBucket or GitLab, or want to create your own custom continuous integration or continuous delivery/deployment system (CI/CD), then you can use the Hydrogen CLI [`deploy`](https://shopify.dev/docs/api/shopify-cli/hydrogen/hydrogen-deploy) command in any context with a valid Oxygen deployment token. *** ## Oxygen deployment tokens The [`deploy`](https://shopify.dev/docs/api/shopify-cli/hydrogen/hydrogen-deploy) command requires a secret Oxygen deployment token. You can create and manage deployment tokens through your storefront settings. If you don't pass a deployment token with the `deploy` command, then the deployment fails. Every Hydrogen [storefront](https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/storefronts) has a default deployment token that's automatically managed by Shopify and can't be removed or edited. If your default token is ever leaked, you can rotate it by clicking the **rotate** icon in your tokens list. ### Create an Oxygen deployment token 1. In the Hydrogen storefront you want to deploy with a custom CI/CD workflow, click **Storefront settings**. 2. Click **Oxygen deployments**. 3. Under **Oxygen deployment tokens** click **Create new token**. 4. Confirm with **Generate new token**. The new token will be added to your token list with a placeholder name. 5. (Optional) Give the token a more descriptive name by clicking the **pencil icon**, typing in your preferred name, then clicking the **check icon**. The token's name has no effect on its functionality. Each token is valid for one year. When it expires, [delete it](#delete-an-oxygen-deployment-token) and create a new one. For security reasons, it's best to create a new token for each service, instead of reusing the same token across different services. ### Delete an Oxygen deployment token Oxygen deployment tokens should be kept secret. If your token ever leaks, delete it and create a new one to keep your storefront secure. 1. In the Hydrogen storefront you want to update, click **Storefront settings**. 2. Click **Oxygen deployments**. 3. Beside the token you want to delete, click the **trash icon**. 4. Click **Delete token** to confirm. *** ## Using Oxygen deployment tokens Once you’ve [created a token](#create-an-oxygen-deployment-token), you can use it with the Hydrogen CLI `deploy` command in any supported context. Oxygen deployment tokens are sensitive and should be kept secret. Most CI/CD platforms offer a way to securely store tokens and other secrets. Check with your service provider about how to securely store and use tokens in your workflows. If your deployment token is exposed, [delete it](#delete-an-oxygen-deployment-token) and create a new one. ### Copy an Oxygen deployment token 1. In the Hydrogen storefront you want to configure CI/CD for, click **Storefront settings**. 2. Click **Oxygen deployments**. 3. Beside the token you want to copy, click the **clipboard icon**. The token value is copied to your clipboard. *** ## Example workflows 1. Copy the generated Oxygen deployment token. 2. Open your CI/CD system's project settings. 3. Locate the section for environment or repository variables. * in Bitbucket go to your project > pipelines > starter pipeline > Add variable * In GitLab go to your project > settings > CI/CD > Variables 1. In your CI/CD create a new variable with the name **SHOPIFY\_HYDROGEN\_DEPLOYMENT\_TOKEN** and not the custom name you created when generating the token. 2. Save the variable in the CI/CD. To run the integration process whenever the watcher branch changes, adjust your workflow or config file. The following are some examples. However every CI/CD is different and might require different inputs. In the following examples, the Oxygen deployment token has been saved as a variable named `SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN`. ### Bitbucket Consult the BitBucket docs for full details on [pipelines](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/) and [variables and secrets](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/). ## bitbucket-pipelines.yml ```yml image: atlassian/default-image:4 pipelines: default: - step: name: 'Build and deploy to Oxygen' script: - npm ci - npx shopify hydrogen deploy --token $SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN ``` ### Git​Lab Consult the GitLab docs for full details on [pipelines](https://docs.gitlab.com/ee/ci/pipelines/index.html) and [variables](https://docs.gitlab.com/ee/ci/variables/). Ensure that the token and branches are not set to [protected](https://docs.gitlab.com/ee/user/project/protected_branches.html). ## .gitlab-ci.yml ```yml stages: - build-and-deploy build-and-deploy: image: node:18 stage: build-and-deploy script: - npm ci - npx shopify hydrogen deploy --token $SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN ``` ### Circle​CI Consult the CircleCI docs for full details about [pipelines](https://circleci.com/docs/pipelines/) and [environment variables](https://circleci.com/docs/env-vars/). ## .circleci/config.yml ```yml # Use the latest 2.1 version of CircleCI pipeline process engine. # See: https://circleci.com/docs/configuration-reference version: 2.1 # Define a job to be invoked later in a workflow. # Refer to https://circleci.com/docs/configuration-reference/#jobs jobs: deploy-hydrogen-storefront-to-oxygen: docker: - image: cimg/node:current steps: - checkout - run: name: "Install Dependencies, Build and Deploy Storefront" command: | npm ci npx shopify hydrogen deploy --token $SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN workflows: storefront-deploy: jobs: - deploy-hydrogen-storefront-to-oxygen ``` ***