semantic-release plugin to publish a GitLab release.
Step | Description |
---|---|
verifyConditions |
Verify the presence and the validity of the authentication (set via environment variables). |
publish |
Publish a GitLab release. |
success |
Add a comment to each GitLab Issue or Merge Request resolved by the release. |
fail |
Open or update a GitLab Issue with information about the errors that caused the release to fail. |
$ npm install @semantic-release/gitlab -D
The plugin can be configured in the semantic-release configuration file:
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"@semantic-release/gitlab",
{
"gitlabUrl": "https://custom.gitlab.com",
"assets": [
{ "path": "dist/asset.min.css", "label": "CSS distribution" },
{ "path": "dist/asset.min.js", "label": "JS distribution", "target": "generic_package" },
{ "path": "dist/asset.min.js", "label": "v${nextRelease.version}.js" },
{ "url": "https://gitlab.com/gitlab-org/gitlab/-/blob/master/README.md" }
]
}
]
]
}
With this example GitLab releases will be published to the https://custom.gitlab.com
instance.
The GitLab authentication configuration is required and can be set via environment variables.
Create a project access token, group access token, or personal access token with role Developer (or higher) and the api
scope and make it available in your CI environment via the GL_TOKEN
environment variable. If you are using GL_TOKEN
as the remote Git repository authentication it must also have the write_repository
scope.
Note: When running with dryRun
only read_repository
scope is required.
Variable | Description |
---|---|
GL_TOKEN or GITLAB_TOKEN |
Required. The token used to authenticate with GitLab. |
GL_URL or GITLAB_URL |
The GitLab endpoint. |
GL_PREFIX or GITLAB_PREFIX |
The GitLab API prefix. |
HTTP_PROXY or HTTPS_PROXY |
HTTP or HTTPS proxy to use. |
NO_PROXY |
Patterns for which the proxy should be ignored. See details below. |
The plugin supports passing requests through a proxy server.
You can configure a proxy server via the HTTPS_PROXY
environment variable: HTTPS_PROXY=http://proxyurl.com:8080
If your proxy server requires authentication embed the username and password in the URL: HTTPS_PROXY=http://user:[email protected]:8080
If your GitLab instance is exposed via plain HTTP (not recommended!) use HTTP_PROXY
instead.
If you need to bypass the proxy for some hosts, configure the NO_PROXY
environment variable: NO_PROXY=*.host.com, host.com
Option | Description | Default |
---|---|---|
gitlabUrl |
The GitLab endpoint. | GL_URL or GITLAB_URL environment variable or CI provided environment variables if running on GitLab CI/CD or https://gitlab.com . |
gitlabApiPathPrefix |
The GitLab API prefix. | GL_PREFIX or GITLAB_PREFIX environment variable or CI provided environment variables if running on GitLab CI/CD or /api/v4 . |
assets |
An array of files to upload to the release. See assets. | - |
milestones |
An array of milestone titles to associate to the release. See GitLab Release API. | - |
successComment |
The comment to add to each Issue and Merge Request resolved by the release. See successComment. | ๐ This issue has been resolved in version ${nextRelease.version} ๐\n\nThe release is available on GitLab release |
successCommentCondition |
Use this as condition, when to comment on issues or merge requests. See successCommentCondition. | - |
failComment |
The content of the issue created when a release fails. See failComment. | Friendly message with links to semantic-release documentation and support, with the list of errors that caused the release to fail. |
failTitle |
The title of the issue created when a release fails. | The automated release is failing ๐จ |
failCommentCondition |
Use this as condition, when to comment on or create an issues in case of failures. See failCommentCondition. | - |
labels |
The labels to add to the issue created when a release fails. Set to false to not add any label. Labels should be comma-separated as described in the official docs, e.g. "semantic-release,bot" . |
semantic-release |
assignee |
The assignee to add to the issue created when a release fails. | - |
Can be a glob or and Array
of
globs and Object
s with the following properties:
Property | Description | Default |
---|---|---|
path |
Required, unless url is set. A glob to identify the files to upload. Supports Lodash templating. |
- |
url |
Alternative to setting path this provides the ability to add links to releases, e.g. URLs to container images. Supports Lodash templating. |
- |
label |
Short description of the file displayed on the GitLab release. Ignored if path matches more than one file. Supports Lodash templating. |
File name extracted from the path . |
type |
Asset type displayed on the GitLab release. Can be runbook , package , image and other (see official documents on release assets). Supports Lodash templating. |
other |
filepath |
A filepath for creating a permalink pointing to the asset (requires GitLab 12.9+, see official documents on permanent links). Ignored if path matches more than one file. Supports Lodash templating. |
- |
target |
Controls where the file is uploaded to. Can be set to project_upload for storing the file as project upload or generic_package for storing the file as generic package. |
project_upload |
status |
This is only applied, if target is set to generic_package . The generic package status. Can be default and hidden (see official documents on generic packages). |
default |
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 String
s 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
.
'dist/*.js'
: include all the js
files in the dist
directory, but not in its sub-directories.
[['dist', '!**/*.css']]
: include all the files in the dist
directory and its sub-directories excluding the css
files.
[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]
: include the dist/MyLibrary.js
and dist/MyLibrary.css
files, and label them MyLibrary JS distribution
and MyLibrary CSS distribution
in the GitLab release.
[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]
: include all the js
and
css
files in the dist
directory and its sub-directories excluding the minified version, plus the
build/MyLibrary.zip
file and label it MyLibrary
in the GitLab release.
The message for the issue comments is generated with Lodash template. The following variables are available:
Parameter | Description |
---|---|
branch |
Object with name , type , channel , range and prerelease properties of the branch from which the release is done. |
lastRelease |
Object with version , channel , gitTag and gitHead of the last release. |
nextRelease |
Object with version , channel , gitTag , gitHead and notes of the release being done. |
commits |
Array of commit Object s with hash , subject , body message and author . |
releases |
Array with a release Object s for each release published, with optional release data such as name and url . |
issue |
A GitLab API Issue object the comment will be posted to, or false when commenting Merge Requests. |
mergeRequest |
A GitLab API Merge Request object the comment will be posted to, or false when commenting Issues. |
The success comment condition is generated with Lodash template. The following variables are available:
Parameter | Description |
---|---|
branch |
Object with name , type , channel , range and prerelease properties of the branch from which the release is done. |
lastRelease |
Object with version , channel , gitTag and gitHead of the last release. |
nextRelease |
Object with version , channel , gitTag , gitHead and notes of the release being done. |
commits |
Array of commit Object s with hash , subject , body message and author . |
releases |
Array with a release Object s for each release published, with optional release data such as name and url . |
issue |
A GitLab API Issue object the comment will be posted to. |
mergeRequest |
A GitLab API Merge Request object the comment will be posted to. |
- do not create any comments at all: set to
false
or templating:"<% return false; %>"
- to only comment on issues:
"<% return issue %>"
- to only comment on merge requests:
"<% return mergeRequest %>"
- you can use labels to filter issues:
"<% return issue.labels?.includes('semantic-release-relevant') %>"
check the GitLab API Merge Request object or the GitLab API Issue object for properties which can be used for the filter
The message for the issue content is generated with Lodash template. The following variables are available:
Parameter | Description |
---|---|
branch |
The branch from which the release had failed. |
errors |
An Array of SemanticReleaseError. Each error has the message , code , pluginName and details properties.pluginName contains the package name of the plugin that threw the error.details contains a information about the error formatted in markdown. |
The failComment
This release from branch ${branch.name} had failed due to the following errors:\n- ${errors.map(err => err.message).join('\\n- ')}
will generate the comment:
This release from branch master had failed due to the following errors:
- Error message 1
- Error message 2
The fail comment condition is generated with Lodash template. The following variables are available:
Parameter | Description |
---|---|
branch |
Object with name , type , channel , range and prerelease properties of the branch from which the release is done. |
lastRelease |
Object with version , channel , gitTag and gitHead of the last release. |
nextRelease |
Object with version , channel , gitTag , gitHead and notes of the release being done. |
commits |
Array of commit Object s with hash , subject , body message and author . |
releases |
Array with a release Object s for each release published, with optional release data such as name and url . |
issue |
A GitLab API Issue object the comment will be posted to - only available if an open issue exists. |
- do not create any comments at all: set to
false
or templating:"<% return false; %>"
- to only comment on main branch:
"<% return branch.name === 'main' %>"
- you can use labels to filter issues, i.e. to not comment if the issue is labeled with
wip
:"<% return !issue.labels?.includes('wip') %>"
check the GitLab API Issue object for properties which can be used for the filter
The latest version of this plugin is compatible with all currently-supported versions of GitLab, which is the current major version and previous two major versions. This plugin is not guaranteed to work with unsupported versions of GitLab.
If you are using GitLab.com or have upgraded your self-hosted GitLab instance to 14.0, please use version >=6.0.7
of this plugin.
In GitLab 14.0, creating a release using the Tags API has been removed (see #290311). This plugin was updated to use the Releases API instead in semantic-release#184, which is available in version 6.0.7
and beyond.