semantic-release
Advanced tools
The semantic-release npm package automates the versioning and package publishing process based on semantic versioning (SemVer) principles. It analyzes commits since the last release to determine the type of version change (major, minor, or patch) and generates a changelog. It then publishes the new version to npm and can also update GitHub/GitLab releases.
Automated Version Management
Automatically analyzes commits, determines the next semantic version, generates a changelog, and publishes the package. The code snippet shows a basic configuration in a package.json file.
"release": {
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/npm",
"@semantic-release/github"
]
}Customizable Plugins
semantic-release's behavior can be customized with plugins. This example configures the commit analyzer and release notes generator to use the Angular preset.
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular"
}],
["@semantic-release/release-notes-generator", {
"preset": "angular"
}],
"@semantic-release/npm",
"@semantic-release/github"
]Continuous Integration (CI) Configuration
Integrates with CI tools like GitHub Actions to automate the release process. This example shows a GitHub Actions workflow that sets up a job for semantic-release.
{
"name": "semantic-release",
"on": {
"push": {
"branches": ["main"]
}
},
"jobs": {
"release": {
"runs-on": "ubuntu-latest",
"steps": [
{
"name": "Checkout repository",
"uses": "actions/checkout@v2"
},
{
"name": "Setup Node.js",
"uses": "actions/setup-node@v1",
"with": {
"node-version": "12"
}
},
{
"name": "semantic-release",
"uses": "semantic-release-plus/docker@v1",
"env": {
"GITHUB_TOKEN": "${{ secrets.GITHUB_TOKEN }}",
"NPM_TOKEN": "${{ secrets.NPM_TOKEN }}"
}
}
]
}
}
}Similar to semantic-release, standard-version automates versioning and CHANGELOG generation based on commit messages, following the Conventional Commits specification. Unlike semantic-release, it does not automatically publish to npm or create GitHub/GitLab releases, focusing instead on versioning and changelog generation.
release-it is a CLI tool for automating versioning and package publishing, similar to semantic-release. It supports plugins for extending functionality but requires more manual configuration for things like generating changelogs and determining version bumps based on commit messages.
While primarily a tool for managing monorepos, Lerna also offers features for automated package publishing similar to semantic-release. It can increment package versions and publish to npm, but it's more focused on managing dependencies and versions across multiple packages in a monorepo.
semantic-release is a toolset to fully automate your package's releases. This will determine not only which version to release, but also when – all without you having to care about it ever again.
This is fully integrated with the npm lifecycle, so all you have to do is to setup your CI to npm publish.
The goal of this package is to remove humans from version numbers and releases. The SemVer spec clearly and unambiguously defines when to increase the major, minor or patch part. Still we tend to ignore the rules, because we are emotionally attached to version numbers.
Conventions, conventions, conventions. Instead of dumping lols into our commit messages, we can take some time to think about what we changed in the codebase and write it down. Following formalized conventions it this then possible to not only generate a meaningful changelog, but to determine the next semantic version to release.
Note: Currently the only supported style is the AngularJS Commit Message Convention style, but feel free to formalize your own style, write a parser for it, and send a PR to this package.
<type>(<scope>): <subject>
<BLANK LINE>
<body>
Examples:
feat(ruler): add inches as well as centimeters
fix(protractor): fix 90 degrees counting as 91 degrees
fix(pen): use blue ink instead of red ink
BREAKING CHANGE: Pen now uses blue ink instead of red.
To migrate, change your code from the following:
`pen.draw('blue')`
To:
`pen.draw('red')`
The preferred configuration is the "try to release on every push" mode. What it does is that everytime a build passes npm publish is executed.
prepublish stepBefore npm actually gets to publish a new version semantic-release's prepublish step does the following:
major|minor|patch) or abort if nothing changedpublish stepnpm does its thing.
postpublish stepAfter npm published the new version the postpublish step does this:
Note: The GitHub Release automatically creates a tag, too.
Note: This is tied to GitHub, feel free to send PRs for other services.
Note: semantic-release works around a limitation in npm's prepublish step. Once a version is published it prints an error that you can safely ignore npm/npm#7118.
First of all you need to install semantic-release and save it as a devDependency.
npm install --save-dev semantic-release
# Btw, if you're feeling lazy you can just type this – it's the same thing.
npm i -D semantic-release
./node_modules/.bin/semantic-release setup
What this does:
The setup command configures scripts inside the package.json:
"scripts": {
"prepublish": "semantic-release pre",
"postpublish": "semantic-release post"
}
Note: If you have already configured scripts for prepublish or postpublish they're just executed one after another. For example: "npm run 6to5 && semantic-release pre".
It would be preferable not to have a version field in the package.json at all, but due to an npm limitation it is required to have a not yet published version in there npm/npm#7118. Because of this the version gets changed to "0.0.0-semantically-released" until npm hopefully removes its limitations.
If you haven't defined your GitHub repository in the package.jsons repository field the remote origin's repository is used.
Inside your .travis.yml:
language: node_js
node_js:
- iojs-v1
sudo: false
cache:
directories:
- node_modules
notifications:
email: false
env:
# Get your token here: https://github.com/settings/tokens/new
# Grant the token repo/public_repo scope (all others can be deselected)
# You should encrypt this:
# `travis encrypt GH_TOKEN=<token> --add`
global: GH_TOKEN=<github-access-token-with-acceess-to-your-repo>
deploy:
provider: npm
email: <your-npm-mail@example.com>
# Very important. Don't forget this one.
skip_cleanup: true
# Travis currently only supports the old auth key format.
# Do `echo -n "<username>:<password>" | base64` to get it.
# You should encrypt this:
# `travis encrypt $(echo -n "<username>:<password>" | base64) --add deploy.api_key`
api_key: <npm-api-key>
on:
branch: master
repo: <user>/<repo>
Note: For once this isn't tied to a specific service, but example configuration is shown for Travis CI. Feel free to contribute configuration of other servers or services.
Note: You should [encrypt](http://docs.travis-ci.com/user/environment-variables/#sts=Secure Variables) your api keys and tokens.
Note: Your CI environment has to export CI=true in order for semantic-release not to automatically perform a dry run. Travis CI does this by default.
Note: It is crucial that your CI server also fetches all tags when checking out your repository. Travis CI does this by default.
Note: If you have a more sophisticated build with multiple jobs you should have a look at travis-after-all, which is also configured for this package.
I think you might frequently ask questions like these
package.json's version not updated in my repository?The npm docs even state:
The most important things in your package.json are the name and version fields. Those are actually required, and your package won't install without them. -- npm docs
While this entirely true the version number doesn't have to be checked into source control. semantic-release takes care of the version field right before npm publish uses it – and this is the only point when it really is required.
If you're running npm publish locally semantic-release automatically performs a dry run. This does log the version that would currently get published, but only if you git fetch --tags before.
Of course you can, but this doesn't mean you should. Running your tests on an independent machine before releasing software is a crucial part of this workflow. Also it is a pain to set this up locally, with GitHub tokens lying around and everything. That said, you can either set the environment variable CI=true, or run the scripts with --debug=false explicitly. Don't forget to export GH_TOKEN=your_token as well.
You can trigger a release by pushing to your repository. You deliberately can not trigger a specific version release, because this is the whole point of semantic-release. Start your packages with 1.0.0 and semver on.
Note: pre-release flags are kind of an exeption here and a solution for them is being thought of. If you have one please open an issue. For the time being: Have a look at the next question.
npm publish?npm offers the --ignore-scripts flag. Doing npm publish --ignore-scripts doesn't execute the prepublish and postpublish scripts.
It is indeed a great idea because it forces you to follow best practices. If you don't feel comfortable making every passing feature or fix on your master branch addressable via npm you might not treat your master right. Have a look at branch workflows. If you still think you should have control over the exact point in time of your release, e.g. because you are following a release schedule, configure your CI server to release only on the production/deploy/release branch and push your code there in certain intervals.
semantic-release with my releases? What if it breaks?semantic-release has a full integration-test suite that tests actual npm publishes and actual GitHub Releases (with private registry/API) on node.js ^0.10, ^0.12 and io.js ^1. A new version won't get published if it doesn't pass on all these engines.
MIT License 2015 © Stephan Bönnemann and contributors
FAQs
Automated semver compliant package publishing
The npm package semantic-release receives a total of 1,083,270 weekly downloads. As such, semantic-release popularity was classified as popular.
We found that semantic-release demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 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.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.