@sanity/semantic-release-preset
v5.0.0
Published
Recommended setup for releasing semantically using GitHub Actions workflows
Downloads
7,070
Maintainers
Readme
@sanity/semantic-release-preset
Features
- Uses Conventional Commits to generate release notes, changelogs and determine the version for new releases.
- Creates or updates a CHANGELOG.md file.
- Publishes to npm.
- Creates a new release on GitHub
- Updates GitHub issues and PRs that are resolved by a new release.
- Commits and pushes the current
version
topackage.json
. - Keep the year in LICENSE up to date.
Table of contents
- Usage
- Next steps, for even more automation
Usage
npm i -D @sanity/semantic-release-preset
If your package manager don't auto install peer dependencies make sure to install semantic-release
:
npm i -D semantic-release
Setup the release config
Create a .releaserc.json
:
{
"extends": "@sanity/semantic-release-preset",
"branches": ["main"]
}
The branches
array is mandatory, and in most repositories you should put the default git branch here (main
, or master
if it's an older repository).
Optional: Configure prerelease branches
If you have stable releases going out from the git branch main
, and want commits on the branch beta
to result in only being installable with the npm dist-tag beta
:
npm i package-name@beta
But not on:
npm i package-name # or npm i package-name@latest
Then use this config:
{
"extends": "@sanity/semantic-release-preset",
"branches": ["main", {"name": "beta", "prerelease": true}]
}
Minimal GitHub Release workflow
This is the bare minimum required steps to trigger a new release. This will push a new release every time an eliglible commit is pushed to git. Check the opinionated flow to see how to trigger releases manually.
Create .github/workflows/ci.yml
:
---
name: CI
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# Need to fetch entire commit history to
# analyze every commit since last release
fetch-depth: 0
- uses: actions/setup-node@v3
with:
cache: npm
node-version: lts/*
- run: npm ci
- run: npm test --if-present
# Branches that will release new versions are defined in .releaserc.json
# @TODO uncomment after verifying with --dry-run we're ready to go
# - run: npx semantic-release
- run: npx semantic-release --dry-run
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
It's important that you use --dry-run
in the npx semantic-release
command until you've verified that semantic-release
is setup correctly and is able to detect your release branches and published version numbers.
If you don't you may accidentally release a wrong version on npm
, know that you can't simply unpublish accidents so it's best to be safe.
You need two secrets, secrets.GITHUB_TOKEN
is always provided to GitHub actions, but if you try to --dry-run
locally you'll need to create a token.
It's easiest to just push commits and inspect the workflow output. You can add --debug
to the npx semantic-release
command to see more verbose logs if there's a tricky error.
The secrets.NPM_PUBLISH_TOKEN
is provided on our GitHub org. If you're outside it you'll need to create it with auth-only
2FA and add it to the repository secrets.
If you're unable to make it work chances are your issue is documented in the semantic-release
troubleshooting docs
Once you've confirmed with --dry-run
that everything is looking good and semantic-release
will perform the actions you expect it to, go ahead and edit .github/workflows/release.yml
:
---
name: CI
on:
# Build on pushes branches that have a PR (including drafts)
pull_request:
# Build on commits pushed to branches without a PR if it's in the allowlist
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# Need to fetch entire commit history to
# analyze every commit since last release
fetch-depth: 0
- uses: actions/setup-node@v3
with:
cache: npm
node-version: lts/*
- run: npm ci
- run: npm test --if-present
# Branches that will release new versions are defined in .releaserc.json
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
If this is on a brand new package that haven't published to npm yet, make a commit like this:
git add .github/workflows/release.yml
git commit -m "feat: initial release"
git push
If you're onboarding a package that already has a published version history:
git add .github/workflows/release.yml
git commit -m "fix: use semantic-release"
git push
Check the Release Workflow docs for more information.
Opinionated GitHub Release workflow
- This flow runs a
build
task for linting and things that only need to run once. - Runs
test
, which runs a matrix of operating systems and Node.js versions. - FInally, runs
release
, if the workflow started from aworkflow_dispatch
, it is skipped onpush
.
TODO more docs are coming, we're actively exploring the optimal setup
Next steps, for even more automation
- Setup Renovatebot dependencies automation with our preset.