For this feature, at least GitLab v11.7 is required. GitLab 11.7 introduces Releases to create release entries (much like GitHub), including release assets. Releases are attached to an existing Git tag, so make sure the Git part is configured correctly.
GitLab releases work just like GitHub releases:
- Configure
gitlab.release: true
. - Obtain a personal access token (release-it only needs the "api" scope).
- Make sure the token is available as an environment variable.
GitLab Releases do not support pre-releases or drafts.
First, release-it will check whether the GITLAB_TOKEN
environment variable is set. Otherwise it will throw an error
and exit. Then, it will authenticate, and verify whether the current user is a collaborator and authorized to publish a
release.
To skip these checks, use gitlab.skipChecks
.
By default, the output of git.changelog
is used for the GitLab release notes. This is the printed Changelog: ...
when release-it boots. This can be overridden with the gitlab.releaseNotes
option to customize the release notes for
the GitLab release. This will be invoked just before the actual GitLab 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:
{
"gitlab": {
"release": true,
"releaseNotes": "generate-release-notes.sh ${latestVersion} ${version}"
}
}
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:
{
gitlab: {
release: true,
releaseNotes(context) {
// Remove the first, redundant line with version and date.
return context.changelog.split('\n').slice(1).join('\n');
}
}
}
See Changelog for more information about generating changelogs/release notes.
To associate one or more milestones with a GitLab release, set the gitlab.milestones
option to an array of the titles
of the corresponding milestones, for example:
{
"gitlab": {
"release": true,
"milestones": ["${version}"]
}
}
Note that creating a GitLab release will fail if one of the given milestones does not exist. release-it will check this
before doing the release. To skip this check, use gitlab.skipChecks
.
To upload binary release assets with a GitLab release (such as compiled executables, minified scripts, documentation),
provide one or more glob patterns for the gitlab.assets
option. After the release, the assets are available to
download from the project's releases page. Example:
{
"gitlab": {
"release": true,
"assets": ["dist/*.dmg"]
}
}
The origin
can be set to a string such as "http://example.org:3000"
to use a different origin from what would be
derived from the Git url (e.g. to use http
over the default https://${repo.host}
).
If you're running your own GitLab instance with an HTTPS certificate issued by a private certificate Authority, you can
specify the root CA certificate with certificateAuthorityFile
, for example:
{
"gitlab": {
"release": true,
"tokenHeader": "PRIVATE-TOKEN",
"certificateAuthorityFile": "./my-root-ca.crt"
}
}
The latest GitLab release can be updated, e.g. to update the releases notes or add release assets.
- Use
--no-increment
to skip updating the version. - Use
--no-git
to skip Git actions. - Use
--no-npm
to skip publishing to npm if there's apackage.json
.
Use the other options to update the release, such as --gitlab.assets
to add assets.
Example command to add assets to the latest release:
release-it --no-increment --no-git --gitlab.release --gitlab.assets=*.zip