---
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/hydrogen/deployments/custom-ci-cd
  md: https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd.md
---

ExpandOn this page

* [Oxygen deployment tokens](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#oxygen-deployment-tokens)
* [Using Oxygen deployment tokens](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#using-oxygen-deployment-tokens)
* [Example workflows](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#example-workflows)

# Deploy from any CI/CD system with deployment tokens

Hydrogen supports [continuous deployment from GitHub](https://shopify.dev/docs/storefronts/headless/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/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
```

***

* [Oxygen deployment tokens](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#oxygen-deployment-tokens)
* [Using Oxygen deployment tokens](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#using-oxygen-deployment-tokens)
* [Example workflows](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments/custom-ci-cd#example-workflows)