CI Configuration
Configure CI to run semantic-release by following two requirements: run it only after all tests pass, and configure the authentication needed to publish releases.
Choose your CI Service
Section titled “Choose your CI Service”Start by choosing your CI service. Each guide shows how to set up your workflow for semantic-release in that CI provider. Then apply the requirements on this page
Run semantic-release only after all tests succeeded
Section titled “Run semantic-release only after all tests succeeded”The semantic-release command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the semantic-release command is executed only after all jobs are successful.
Authentication
Section titled “Authentication”semantic-release requires authentication to push to your repository and publish releases. Several authentication methods are available depending on your CI service and repository hosting platform.
Push access to the remote repository
Section titled “Push access to the remote repository”semantic-release requires push access to the project Git repository in order to create Git tags. The Git authentication can be set with one of the following environment variables:
| Variable | Description |
|---|---|
GH_TOKEN or GITHUB_TOKEN | A GitHub personal access token. Note: In GitHub Actions, GITHUB_TOKEN is automatically provided by the runner. |
GL_TOKEN or GITLAB_TOKEN | A GitLab personal access token. |
BB_TOKEN or BITBUCKET_TOKEN | A Bitbucket personal access token. |
BB_TOKEN_BASIC_AUTH or BITBUCKET_TOKEN_BASIC_AUTH | A Bitbucket personal access token with basic auth support. For clarification user:token has to be the value of this env. |
GIT_CREDENTIALS | URL encoded Git username and password in the format <username>:<password>. The username and password must each be individually URL encoded, not the : separating them. |
Alternatively the Git authentication can be set up via SSH keys.
Authentication for plugins
Section titled “Authentication for plugins”Most semantic-release plugins require setting up authentication in order to publish to a package manager registry. The default @semantic-release/npm and @semantic-release/github plugins require the following environment variables:
| Variable | Description |
|---|---|
NPM_TOKEN | npm token for publishing to npm. Trusted publishing is now the preferred approach where supported. See CI configuration recipes for details on setup options. |
GH_TOKEN | GitHub authentication token for publishing releases. See CI configuration recipes for setup options. |
See each plugin’s documentation for the environment variables required.
The authentication token/credentials have to be made available in the CI service via environment variables.
See CI configuration recipes for examples of how to configure environment variables in your CI service.
Note: The environment variables GH_TOKEN, GITHUB_TOKEN, GL_TOKEN and GITLAB_TOKEN can be used for both the Git authentication and the API authentication required by @semantic-release/github and @semantic-release/gitlab.