# Configuration

**semantic-release** configuration consists of:
- Git repository [url](#repositoryurl) and options ([release branch](#branch) and [tag format](#tagformat)). ([Access credentials](ci-configuration.md) are setup through environment variables)
- Plugins [declaration](#plugins) and [options](plugins.md).
- Run mode ([`--dry-run`](#dryrun), [`--no-ci`](#ci) (local), [`--debug`](#debug)).

All of these options can be configured:
- In a config file.
- Through the cli.
- By extending a [shareable configuration](shareable-configurations.md).

Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables).

## Configuring/passing options to `semantic-release`

### Configuration file

> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.

**semantic-release**’s options, mode and plugins can be set via a config file in different ways:
- A `.releaserc` file, written in YAML or JSON, with optional extensions `.yaml`, `.yml`, `.json` or `.js`.
- A `release.config.js` file that exports an object.
- A `release` key in the project's `package.json` file.

The following two examples are the same:
- Via `.releaserc` or `release.config.js` file:    
    ```json
    {
      "branch": "next"
    }
    ```
- Via `release` key in the project's `package.json` file (the configuration must be under the `release` property):
    ```json
    {
      "release": {
        "branch": "next"
      }
    }
    ```

### Using CLI arguments

> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.

Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.

The following configuration example via CLI argument is equivalent to the configuration file's example:

```bash
$ semantic-release --branch next
```

### Extending a shareable configuration

> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.

Please see [shareable configuration](shareable-configurations.md) for more details.

## Options

### `extends`

Type: `Array`, `String`<br>
CLI arguments: `-e`, `--extends`

Contains a list of:
- Modules.
- File paths containing a [shareable configuration](shareable-configurations.md). 

> **Note**:  If multiple shareable configurations are set, they will be imported **in the order defined with each configuration option** taking precedence over the options defined in a previous shareable configuration.

Examples (`.releaserc` file content):
- `Array`:
    ```json
    {
      "extends": [
        "./my_config_dir/my.config",
        "@semantic-release/gitlab-config",
      ]
    }
    ```
- `String`:
    ```json
    {
      "extends": "@semantic-release/gitlab-config"
    }
    ```

### `branch`

Type: `String`<br>
Default: `master`<br>
CLI arguments: `-b`, `--branch`

The branch on which releases should happen.

Example (`.releaserc` file content):
```json
{
  "branch": "next"
}
```

### `repositoryUrl`

Type: `String`<br>
Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)<br>
CLI arguments: `-r`, `--repository-url`

The git repository URL.

Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)).

Example (`.releaserc` file content):
```json
{
  "repositoryUrl": "https://github.com/username/project.git"
}
```

### `tagFormat`

Type: `String`<br>
Default: `v${version}`<br>
CLI arguments: `-t`, `--tag-format`

The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) format used by **semantic-release** to identify releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template) and will be compiled with the `version` variable.

> **Note**: The `tagFormat` must contain the `version` variable exactly once and compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description).

Example (`.releaserc` file content):
```json
{
  "tagFormat": "version-${version}"
}
```

### `plugins`

Type: `Array`<br>
Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`<br>
CLI arguments: `-p`, `--plugins`

Define the list of plugins to use. Plugins will run in series, **in the order defined**, for **each [steps](../../README.md#release-steps)** if they implement it.

Plugin specific configuration can defined by wrapping the name and an options object in an array. See [Plugins configuration options](plugins.md#plugins-configuration-options) for more details.

Example (`.releaserc` file content):
```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release-docker",
    ["@semantic-release/exec", {
      "verifyConditionsCmd": "./verify.sh"
    }],
    "@semantic-release/git",
    "@semantic-release/gitlab",
  ]
}
```
### `dryRun`

Type: `Boolean`<br>
Default: `false` if running in a CI environment, `true` otherwise<br>
CLI arguments: `-d`, `--dry-run`

Dry-run mode, skip publishing, print next version and release notes.

Example (`.releaserc` file content):
```json
{
  "dryRun": "true"
}
```

### `ci`

Type: `Boolean`<br>
Default: `true`<br>
CLI arguments: `--ci` / `--no-ci`

Set to `false` to skip Continuous Integration environment verifications. This allows for making releases from a local machine.

> **Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`.

Example (`.releaserc` file content):
```json
{
  "ci": "false"
}
```

### `debug` (only through CLI)

Type: `Boolean`<br>
Default: `false`<br>
CLI argument: `--debug`

Output debugging information. This can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.

> **Note**: The `debug` is used only supported via CLI argument. To enable debug mode from the [JS API](../04-developer-guide/js-api.md#javascript-api) use `require('debug').enable('semantic-release:*')`.

Example:
```bash
$ semantic-release --debug
```

## Git environment variables

| Variable              | Description                                                                                                                                                                                                                    | Default                              |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
| `GIT_AUTHOR_NAME`     | The author name associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing).     | @semantic-release-bot.               |
| `GIT_AUTHOR_EMAIL`    | The author email associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing).    | @semantic-release-bot email address. |
| `GIT_COMMITTER_NAME`  | The committer name associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing).  | @semantic-release-bot.               |
| `GIT_COMMITTER_EMAIL` | The committer email associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing). | @semantic-release-bot email address. |

## Existing version tags, and how semantic-release deals with them

**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. 

If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branch](#branch) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).

If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.

For example, if your release branch is `master`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `master` history and is tagged with `v1.1.0`.

```bash
# Make sure the commit 1234567 is in the release branch history
$ git branch --contains 1234567

# If the commit is not in the branch history it means that either:
# - you use a different branch than the one your release from before
# - or the commit sha has been rewritten (with git rebase)
# In both cases you need to configure your repository to have the last release commit in the history of the release branch

# List the tags for the commit 1234567
$ git tag --contains 1234567

# If v1.1.0 is not in the list you add it with
$ git tag v1.1.0 1234567
$ git push origin v1.1.0
```