|
|
- # Configuration
-
- **semantic-release** configuration consist of:
- - Git repository options ([URL](#repositoryurl), [release branch](#branch) and [tag format](#tagformat))
- - [plugins](#plugins) definition
- - run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
-
- All those options can be configured directly or 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).
-
- ## Configuration file
-
- **semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via:
- - A `.releaserc` file, written in YAML or JSON, with optional extensions: .`yaml`/`.yml`/`.json`/`.js`
- - A `release.config.js` file that exports an object
- - A `release` key in the project's `package.json` file
-
- Alternatively some options can be set via CLI arguments.
-
- The following three examples are the same.
-
- Via `release` key in the project's `package.json` file:
-
- ```json
- {
- "release": {
- "branch": "next"
- }
- }
- ```
- ```bash
- $ semantic-release
- ```
-
- Via `.releaserc` file:
-
- ```json
- {
- "branch": "next"
- }
- ```
- ```bash
- $ semantic-release
- ```
-
- Via CLI argument:
-
- ```bash
- $ semantic-release --branch next
- ```
-
- **Note**: CLI arguments take precedence over options configured in the configuration file.
-
- **Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
-
- **Note**: When configuring via `package.json`, the configuration must be under the `release` property. However, when using a `.releaserc` or a `release.config.js` file, the configuration must be set without a `release` property.
-
- ## Options
-
- ### extends
-
- Type: `Array`, `String`<br>
- CLI arguments: `-e`, `--extends`
-
- List of modules or file paths containing a [shareable configuration](shareable-configurations.md). 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.
-
- **Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
-
- ### branch
-
- Type: `String`<br>
- Default: `master`<br>
- CLI arguments: `-b`, `--branch`
-
- The branch on which releases should happen.
-
- ### 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)).
-
- ### 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).
-
- ### 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.
-
- Plugins configuration can defined by wrapping the name and an options object in an array.
-
- See [Plugins configuration](plugins.md#plugins) for more details.
-
- ### 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.
-
- ### 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`.
-
- ### debug
-
- Type: `Boolean`<br>
- Default: `false`<br>
- CLI argument: `--debug`
-
- Output debugging information. It can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.
-
- ## 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
-
- **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 have 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
- ```
|