# CI configuration

## Running `semantic-release`

The `semantic-release` command will only run fully in a CI environment. If it does not detect that it is in a CI environment, it will automatically run in `dry-run` mode.
 
Within a CI environment, the `semantic-release` command must be executed only after all the tests in the CI build pass, otherwise it will release potentially faulty code. 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. 

Follow the CI system's documentation to find out how to do this:
- [Travis Build Stages](https://docs.travis-ci.com/user/build-stages)
- [CircleCI Workflows](https://circleci.com/docs/2.0/workflows)
- [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines)
- [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html#introduction-to-pipelines-and-jobs)
- [Codefresh Pipelines](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines)
- [Wercker Workflows](http://devcenter.wercker.com/docs/workflows)
- [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).

This documentation provides a few [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details.

## Authentication

### Push access to remote repos

**semantic-release** requires push access to remote Git repositories in order to push the [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it created.

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](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line).                                                                                                    |
| `GL_TOKEN` or `GITLAB_TOKEN`    | A GitLab [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html).                                                                                                                       |
| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html).                                                                                                 |
| `GIT_CREDENTIALS`               | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) 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](../03-recipes/git-auth-ssh-keys.md)**.

### Authentication needs for plugins

Most **semantic-release** [plugins](plugins.md) require setting up authentication in order to publish to a package manager registry. See each plugin's documentation for the environment variables required.

It is to note, however, that:
- The default [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugin requires the same `GH_TOKEN` environment variable as above
- The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) plugin requires the following environment variables:

| Variable    | Description                                                                                                                                                                                                                                                                                                               |
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `NPM_TOKEN` | npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens).<br/>**Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported. |

See each plugin's documentation for the environment variables required.

> **Note**: The authentication token/credentials have to be made available in the CI service via environment variables.
>
> See [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on how to configure environment variables in your CI service.