# Configuration **semantic-release** configuration consists of: * Git repository ([URL](#repositoryurl) and options [release branches](#branches) and [tag format](#tagformat)) * Plugins [declaration](#plugins) and options * Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci)) All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](https://semantic-release.gitbook.io/semantic-release/beta/usage/shareable-configurations). 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](https://semantic-release.gitbook.io/semantic-release/beta/usage/plugins) can be set via either: * 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: ```javascript { "release": { "branches": ["master", "next"] } } ``` * Via `.releaserc` file: ```javascript { "branches": ["master", "next"] } ``` * Via CLI argument: ```bash $ semantic-release --branches 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`\ CLI arguments: `-e`, `--extends` List of modules or file paths containing a [shareable configuration](https://semantic-release.gitbook.io/semantic-release/beta/usage/shareable-configurations). 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. ### branches Type: `Array`, `String`, `Object`\ Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`\ CLI arguments: `--branches` The branches on which releases should happen. By default **semantic-release** will release: * regular releases to the default distribution channel from the branch `master` * regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a number) * regular releases to the `next` distribution channel from the branch `next` if it exists * regular releases to the `next-major` distribution channel from the branch `next-major` if it exists * prereleases to the `beta` distribution channel from the branch `beta` if it exists * prereleases to the `alpha` distribution channel from the branch `alpha` if it exists **Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` branch. **Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://docs.github.com/github/administering-a-repository/about-protected-branches). See [Workflow configuration](https://semantic-release.gitbook.io/semantic-release/beta/workflow-configuration#workflow-configuration) for more details. ### repositoryUrl Type: `String`\ Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)\ 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`\ Default: `v${version}`\ 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`\ Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`\ CLI arguments: `-p`, `--plugins` Define the list of plugins to use. Plugins will run in series, in the order defined, for each [steps](https://semantic-release.gitbook.io/semantic-release/beta/undefined#release-steps) if they implement it. Plugins configuration can defined by wrapping the name and an options object in an array. See [Plugins configuration](https://semantic-release.gitbook.io/semantic-release/beta/plugins#plugins) for more details. ### dryRun Type: `Boolean`\ Default: `false` if running in a CI environment, `true` otherwise\ CLI arguments: `-d`, `--dry-run` The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, success and fail. In addition to this it prints the next version and release notes to the console. **Note**: The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues. ### ci Type: `Boolean`\ Default: `true`\ 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`\ Default: `false`\ 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](https://semantic-release.gitbook.io/semantic-release/beta/developer-guide/js-api#javascript-api) use `require('debug').enable('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 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 branches](#branches) 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://semantic-release.gitbook.io/semantic-release/beta/usage/configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.