@semantic-release/git
Advanced tools
@semantic-release/git is a plugin for semantic-release that allows you to commit files to the Git repository as part of the release process. This can be useful for updating version numbers, changelogs, or any other files that need to be committed after a release.
Commit files to the repository
This feature allows you to commit specified files (e.g., package.json, CHANGELOG.md) to the repository with a custom commit message after a release.
{
"plugins": [
[
"@semantic-release/git",
{
"assets": ["package.json", "CHANGELOG.md"],
"message": "chore(release): ${nextRelease.version} [skip ci]"
}
]
]
}Skip CI for release commits
This feature allows you to add a [skip ci] flag to the commit message to prevent CI pipelines from running on release commits.
{
"plugins": [
[
"@semantic-release/git",
{
"message": "chore(release): ${nextRelease.version} [skip ci]"
}
]
]
}Customizable commit message
This feature allows you to customize the commit message used for the release commit.
{
"plugins": [
[
"@semantic-release/git",
{
"message": "Release version ${nextRelease.version}"
}
]
]
}standard-version is a utility for versioning and changelog generation, with a focus on conventional commits. It provides similar functionality to @semantic-release/git by automating the version bumping and changelog generation, but it is not as tightly integrated into the semantic-release ecosystem.
release-it is a versatile release automation tool that can handle version bumping, changelog generation, and GitHub/GitLab releases. It offers more flexibility and customization options compared to @semantic-release/git, but may require more configuration.
lerna is a tool for managing JavaScript projects with multiple packages. It can automate the versioning and publishing process for monorepos, similar to @semantic-release/git, but is specifically designed for managing multi-package repositories.
Set of Semantic-release plugins for publishing to a git repository.
Verify the access to the remote Git repository, the commit message format and the assets option configuration.
Create a release commit, including configurable files.
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.
| 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 | 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. See assets. | ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'] |
Note: If you use a shareable configuration that defines one of these options you can set it to false in your semantic-release configuration in order to use the default value.
messageThe 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. |
lastRelease | Object with version, gitTag and gitHead of the last release. |
nextRelease | Object with version, gitTag, gitHead and notes of the release being done. |
It is recommended to include [skip ci] in the commit message to not trigger a new build.
Note: Some CI service support the [skip ci] keyword only in the subject of the message.
message examplesThe 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]
## 1.0.0
### Features
* Generate 1.21 gigawatts of electricity
...
assetsCan be an Array or a single entry. Each entry can be either:
Each entry in the assets Array is globbed individually. A glob can be a String ("dist/**/*.js" or "dist/mylib.js") or an Array of Strings that will be globbed together (["dist/**", "!**/*.css"]).
If a directory is configured, all the files under this directory and its children will be included.
Note: If a file has a match in assets it will be included even if it also has a match in .gitignore.
assets examples'dist/*.js': include all js files in the dist directory, but not in its sub-directories.
'dist/**/*.js': include all js files in the dist directory and its sub-directories.
[['dist', '!**/*.css']]: include all files in the dist directory and its sub-directories excluding the css files.
[['dist', '!**/*.css'], 'package.json']: include package.json and all files in the dist directory and its sub-directories excluding the css files.
[['dist/**/*.{js,css}', '!**/*.min.*']]: include all js and css files in the dist directory and its sub-directories excluding the minified version.
Options can be set within the plugin definition in the Semantic-release configuration file:
{
"release": {
"prepare": [
"@semantic-release/npm",
{
"path": "@semantic-release/git",
"assets": ["package.json", "dist/**/*.{js,css}", "docs"],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}
],
"publish": ["@semantic-release/github"]
}
}
When using with the changelog or npm plugins:
package.json file so the git plugin can include it in the release commit.To use with the changelog and npm plugins:
{
"release": {
"verifyConditions": ["@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git"],
"prepare": ["@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git"]
}
}
Using GPG, you can sign and verify tags and commits. With GPG keys, the release tags and commits made by Semantic-release are verified and other people can trust that they were really were made by your account.
If you already have a GPG public and private key you can skip this step and go to the Get the GPG keys ID and the public key content step.
Download and install the GPG command line tools for your operating system.
Create a GPG key
$ gpg --full-generate-key
At the prompt select the RSA and RSA king of key, enter 4096 for the keysize, specify how long the key should be valid, enter yout name, the email associated with your Git hosted account and finally set a long and hard to guess passphrase.
Use the gpg --list-secret-keys --keyid-format LONG command to list your GPG keys. From the list, copy the GPG key ID you just created.
$ gpg --list-secret-keys --keyid-format LONG
/Users/<user_home>/.gnupg/pubring.gpg
---------------------------------------
sec rsa4096/XXXXXXXXXXXXXXXX 2017-12-01 [SC]
uid <your_name> <your_email>
ssb rsa4096/YYYYYYYYYYYYYYYY 2017-12-01 [E]
the GPG key ID if 16 character string, on the on the sec line, after rsa4096. In this example, the GPG key ID is XXXXXXXXXXXXXXXX.
Export the public key (replace XXXXXXXXXXXXXXXX with your key ID):
$ gpg --armor --export XXXXXXXXXXXXXXXX
Copy your GPG key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----
In GitHub Settings, click on SSH and GPG keys in the sidebar, then on the New GPG Key button.
Paste the entire GPG key export previously and click the Add GPG Key button.
See Adding a new GPG key to your GitHub account for more details.
If you want to use this GPG to also sign the commits and tags you create on your local machine you can follow the instruction at Git Tools - Signing Your Work This step is optional and unrelated to Semantic-release.
Make the public and private GPG key available on the CI environment. Encrypt the keys, commit it to your repository and configure the CI environment to decrypt it.
Install the Travis CLI:
$ gem install travis
Login to Travis with the CLI:
$ travis login
Add the following environment variables to Travis:
GPG_PASSPHRASE to Travis with the value set during the GPG keys generation stepGPG_KEY_ID to Travis with the value of your GPG key ID retrieved during the GPG keys generation (replace XXXXXXXXXXXXXXXX with your key ID)GIT_EMAIL with the email address you set during the GPG keys generation stepGIT_USERNAME with the name you set during the GPG keys generation step$ travis env set GPG_PASSPHRASE <gpg_passphrase>
$ travis env set GPG_KEY_ID XXXXXXXXXXXXXXXX
$ travis env set GIT_EMAIL <your_email>
$ travis env set GIT_USERNAME <your_name>
From your repository root export your public and private GPG keys in the git_gpg_keys.asc (replace XXXXXXXXXXXXXXXX with your key ID):
$ gpg --export -a XXXXXXXXXXXXXXXX > git_gpg_keys.asc
$ gpg --export-secret-key -a XXXXXXXXXXXXXXXX >> git_gpg_keys.asc
Encrypt the git_gpg_keys.asc (public and private key) using a symmetric encryption (AES-256), and store the secret in a secure environment variable in the Travis environment:
$ travis encrypt-file git_gpg_keys.asc
The travis encrypt-file will encrypt the keys into the git_gpg_keys.asc.enc file and output in the console the command to add to your .travis.yml file. It should look like openssl aes-256-cbc -K $encrypted_AAAAAAAAAAAA_key -iv $encrypted_BBBBBBBBBBBB_iv -in git_gpg_keys.asc.enc -out git_gpg_keys.asc -d.
Copy this command to your .travis.yml file in the before_install step. Change the output path to write the unencrypted key in /tmp: -out git_gpg_keys.asc => /tmp/git_gpg_keys.asc. This will avoid to commit / modify / delete the unencrypted keys by mistake on the CI. Then add the commands to decrypt the GPG keys and make it available to git:
before_install:
# Decrypt the git_gpg_keys.asc.enc key into /tmp/git_gpg_keys.asc
- openssl aes-256-cbc -K $encrypted_AAAAAAAAAAAA_key -iv $encrypted_BBBBBBBBBBBB_iv -in git_gpg_keys.asc.enc -out /tmp/git_gpg_keys.asc -d
# Make sure only the current user can read the keys
- chmod 600 /tmp/git_gpg_keys.asc
# Import the gpg key
- gpg --batch --yes --import /tmp/git_gpg_keys.asc
# Create a script that pass the passphrase to the gpg CLI called by git
- echo '/usr/bin/gpg2 --passphrase ${GPG_PASSPHRASE} --batch --no-tty "$@"' > /tmp/gpg-with-passphrase && chmod +x /tmp/gpg-with-passphrase
# Configure git to use the script that passes the passphrase
- git config gpg.program "/tmp/gpg-with-passphrase"
# Configure git to sign the commits and tags
- git config commit.gpgsign true
# Configure git to use your GPG key
- git config --global user.signingkey ${GPG_KEY_ID}
See Encrypting Files for more details.
Delete the local keys as it won't be used anymore:
$ rm git_gpg_keys.asc
Commit the encrypted keys and the .travis.yml file to your repository:
$ git add git_gpg_keys.asc.enc .travis.yml
$ git commit -m "ci(travis): Add the encrypted GPG keys"
$ git push
FAQs
semantic-release plugin to commit release assets to the project's git repository
The npm package @semantic-release/git receives a total of 922,476 weekly downloads. As such, @semantic-release/git popularity was classified as popular.
We found that @semantic-release/git demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.