The "releases" page on GitHub projects links to a page containing the project's history, or changelog. Releases are attached to an existing Git tag, so make sure the Git part is configured correctly.
Unsurprisingly, release-it uses this feature extensively (release-it's releases page).
See the screenshot on the right for an overview of what release-it automates.
To add GitHub releases in your release-it flow, there are two options:
- Automated. This requires a personal access token.
- Manual. The GitHub web interface will be opened with pre-populated fields.
To automate the release (using the GitHub REST API), the following needs to be configured:
- Configure
github.release: true
- Obtain a personal access token (release-it only needs "repo" access; no "admin" or other scopes).
- Make sure the token is available as an environment variable.
Do not put the actual token in the release-it configuration. It will be read from the GITHUB_TOKEN
environment
variable. You can change this variable name by setting the github.tokenRef
option to something else.
Optionally, release-it can automatically submit comments to the merged pull requests and closed tickets to notify people in which release the fix or feature is included.
In this mode, release-it will open the default browser pointed at the GitHub web interface with the fields pre-populated (like the screenshot above). The data can be modified and assets can be uploaded before publishing the release.
- Configure
github.release: true
- This mode is enabled automatically when the
GITHUB_TOKEN
environment variable is not set. - Set
github.web: true
explicitly to override thisGITHUB_TOKEN
check. - Use
github.autoGenerate: true
to let GitHub generate release notes.
In non-interactive CI mode (using --ci
or in a CI environment), release-it will not open a browser, but instead print
the url to the GitHub web interface (including data to pre-populate the fields).
A GitHub release requires the corresponding Git tag to be present on the remote (release-it creates and pushes this tag
automatically). Thus, in addition to the GITHUB_TOKEN
, a public SSH key is required to push the Git tag to the remote
repository. See Git remotes (and CI: Git) for more information.
First, release-it will check whether the GITHUB_TOKEN
environment variable is set. If not, it will fall back to open
the web interface to publish a release (and skip the next checks). If the token is set, it will authenticate, and
verify whether the current user is a collaborator and authorized to publish a release.
To skip these checks, use github.skipChecks
.
The default release name is Release ${version}
. However, many projects are more creative here. It can be set from the
command-line directly: --github.releaseName="Arcade Silver"
.
By default, the output of git.changelog
is used for the GitHub release notes. This is the printed Changelog: ...
when release-it boots. This can be overridden with the github.releaseNotes
option to customize the release notes for
the GitHub release. This will be invoked just before the actual GitHub release itself.
The value can either be a string or a function but a function is only supported when configuring release-it using
.release-it.js
or .release-it.cjs
file.
When the value is a string, it's executed as a shell script. Make sure it outputs to stdout
. An example:
{
"github": {
"release": true,
"releaseNotes": "generate-release-notes.sh --from=${latestTag} --to=${tagName}"
}
}
Another example using --no-merges
to omit merge commits:
{
"github": {
"release": true,
"releaseNotes": "git log --no-merges --pretty=format:\"* %s %h\" ${latestTag}...main"
}
}
When the value is a function, it's executed with a single context
parameter that contains the plugin context. The
function can also be async
. Make sure that it returns a string value. An example:
{
github: {
release: true,
releaseNotes(context) {
// Remove the first, redundant line with version and date.
return context.changelog.split('\n').slice(1).join('\n');
}
}
}
Use --github.autoGenerate
to have GitHub auto-generate the release notes (does not work with web: true
).
See Changelog for more information about generating changelogs/release notes.
To upload binary release assets with a GitHub release (such as compiled executables, minified scripts, documentation),
provide one or more glob patterns for the github.assets
option. After the release, the assets are available to
download from the GitHub release page. Example:
{
"github": {
"release": true,
"assets": ["dist/*.zip"]
}
}
If the release is a pre-release (according to semver), release-it automatically sets github.preRelease
to true
. This
can also be set manually.
In case the release should not be made public yet, set github.draft: true
.
Use a different host from what would be derived from the Git url (e.g. when using GitHub Enterprise).
By default, the GitHub API host is https://api.github.com. Setting github.host
to "private.example.org"
would
result in release-it using https://private.example.org/api/v3.
In case release are done from behind a proxy, set github.proxy
using a string to a proxy address like
"http://proxy:8080"
.
The latest GitHub release can be updated, e.g. to update the releases notes, add release assets, or toggle the draft
status.
- Use
--no-increment
to skip updating the version. - Use
--no-git
to skip Git commit, tag, push (when the tag is already there). - Use
--no-npm
to skip publishing to npm (if there's apackage.json
). - Use
--github.update
to update the GitHub release.
Use the other options to update the release, such as --github.assets
to add assets. Note that the draft
and
preRelease
options are false
by default, but can be set explicitly using e.g. --no-github.draft
or
--github.draft
.
Example command to add assets and explicitly toggle the draft status to "published":
release-it --no-increment --no-git --github.release --github.update --github.assets=*.zip --no-github.draft
To submit a comment to each merged pull requests and closed issue that is part of the release, set
github.comments.submit
to true
. Here are the default settings:
{
"github": {
"comments": {
"submit": false,
"issue": ":rocket: _This issue has been resolved in v${version}. See [${releaseName}](${releaseUrl}) for release notes._",
"pr": ":rocket: _This pull request is included in v${version}. See [${releaseName}](${releaseUrl}) for release notes._"
}
}
}
Example comment:
馃殌 This issue has been resolved in v15.10.0. See Release 15.10.0 for release notes.
This only works with github.release: true
and not with manual release via the web interface.
Since this is an experimental feature, it's disabled by default for now. Set github.comments: true
to enable.