Deploy from any CI/CD system with deployment tokens

Hydrogen supports continuous deployment from 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 command in any context with a valid Oxygen deployment token.

Anchor to Oxygen deployment tokensOxygen deployment tokens

The 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 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.

Anchor to Create an Oxygen deployment tokenCreate 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 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.

Anchor to Delete an Oxygen deployment tokenDelete 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.

Anchor to Using Oxygen deployment tokensUsing Oxygen deployment tokens

Once you’ve created a 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 and create a new one.

Anchor to Copy an Oxygen deployment tokenCopy 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.

Anchor to Example workflowsExample 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.

Anchor to BitbucketBitbucket

Consult the BitBucket docs for full details on pipelines and variables and secrets.

Anchor to GitLabGitLab

Consult the GitLab docs for full details on pipelines and variables. Ensure that the token and branches are not set to protected.

Anchor to CircleCICircleCI

Consult the CircleCI docs for full details about pipelines and environment variables.