5a5eaec3da
This is a first step to improving the doc: - renamed directories; - augmented a fair bit of content. To be continued
246 lines
9.4 KiB
Markdown
246 lines
9.4 KiB
Markdown
# 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" # plugin configuration
|
||
}],
|
||
"@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
|
||
```
|