@semantic-release/git

semantic-release plugin to commit release assets to the project's git repository.

[!WARNING] You likely do not need this plugin to accomplish your goals with semantic-release.
Please consider our recommendation against making commits during your release to avoid unnecessary headaches.

| Step | Description | |--------------------|------------------------------------------------------------------------------------------------------------------------------------| | verifyConditions | Verify the access to the remote Git repository, the commit message and the assets option configuration. | | prepare | Create a release commit, including configurable file assets. |

Install

$ npm install @semantic-release/git -D

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/git", {
      "assets": ["dist/**/*.{js,css}", "docs", "package.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }]
  ]
}

With this example, for each release a release commit will be pushed to the remote Git repository with:

• a message formatted like chore(release): <version> [skip ci]\n\n<release notes>
• the .js and .css files in the dist directory, the files in the docs directory and the package.json

Merging between semantic-release branches

This plugin will, by default, create commit messages with the keyword [skip ci], so they won't trigger a new unnecessary CI build. If you are using semantic-release with multiple branches, when merging a branch with a head being a release commit, a CI job will be triggered on the target branch. Depending on the CI service that might create an unexpected behavior as the head of the target branch might be ignored by the build due to the [skip ci] keyword.

To avoid any unexpected behavior we recommend to use the --no-ff option when merging branches used by semantic-release.

Note: This concerns only merges done between two branches configured in the branches option.

Configuration

Git authentication

The Git user associated with the Git credentials has to be able to push commit to the release branch.

When configuring branches permission on a Git hosting service (e.g. GitHub protected branches, GitLab protected branches or Bitbucket branch permissions) it might be necessary to create a specific configuration in order to allow the semantic-release user to bypass global restrictions. For example on GitHub you can uncheck "Include administrators" and configure semantic-release to use an administrator user, so the plugin can push the release commit without requiring status checks and pull request reviews.

Environment variables

| Variable | Description | Default | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------| | GIT_AUTHOR_NAME | The author name associated with the release commit. See Git environment variables. | @semantic-release-bot. | | GIT_AUTHOR_EMAIL | The author email associated with the release commit. See Git environment variables. | @semantic-release-bot email address. | | GIT_COMMITTER_NAME | The committer name associated with the release commit. See Git environment variables. | @semantic-release-bot. | | GIT_COMMITTER_EMAIL | The committer email associated with the release commit. See Git environment variables. | @semantic-release-bot email address. |

Options

| Options | Description | Default | |-----------|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | message | The message for the release commit. See message. | chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes} | | assets | Files to include in the release commit. Set to false to disable adding files to the release commit. See assets. | ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'] |

message

The message for the release commit is generated with Lodash template. The following variables are available:

| Parameter | Description | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | branch | The branch from which the release is done. | | branch.name | The branch name. | | branch.type | The type of branch. | | branch.channel | The distribution channel on which to publish releases from this branch. | | branch.range | The range of semantic versions to support on this branch. | | branch.prerelease | The pre-release detonation to append to semantic versions released from this branch. | | lastRelease | Object with version, gitTag and gitHead of the last release. | | nextRelease | Object with version, gitTag, gitHead and notes of the release being done. |

Note: It is recommended to include [skip ci] in the commit message to not trigger a new build. Some CI service support the [skip ci] keyword only in the subject of the message.

message examples

The message Release <%= nextRelease.version %> - <%= new Date().toLocaleDateString('en-US', {year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: 'numeric' }) %> [skip ci]\n\n<%= nextRelease.notes %> will generate the commit message:

Release v1.0.0 - Oct. 21, 2015 1:24 AM [skip ci]<br><br>## 1.0.0<br><br>### Features<br>* Generate 1.21 gigawatts of electricity<br>...

assets

Can be an Array or a single entry. Each entry can be either:

• a glob
• or an Object with a path property containing a glob.

Each entry in the assets Array is globbed individually. A [glob](https://github.com/micro