@semantic-release/gitlab

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. |

Install

``bash
$ npm install @semantic-release/gitlab -D
`

Usage

The plugin can be configured in the semantic-release configuration file:

`json
{
"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", "label": "README.md" }
]
}
]
]
}
`

With this example GitLab releases will be published to the https://custom.gitlab.com instance.

Configuration

$3

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.

#### Using a CI Job Token

When running in a GitLab CI/CD environment, you can use the CI_JOB_TOKEN for authentication. To enable this, set the useJobToken option to true in your plugin configuration:

`json
{
"plugins": [["@semantic-release/gitlab", { "useJobToken": true }]]
}
`

> Important: When useJobToken is enabled, comments on issues and merge requests are automatically disabled. This is due to the limited permissions of the CI_JOB_TOKEN which do not allow for these actions.

$3

| 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. |
| CI_JOB_TOKEN | The GitLab CI/CD job token. Used if useJobToken is true. |
| HTTP_PROXY or HTTPS_PROXY | HTTP or HTTPS proxy to use. |
| NO_PROXY | Patterns for which the proxy should be ignored. See details below. |

#### Proxy configuration

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:pwd@proxyurl.com: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

$3

| 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. |
| useJobToken | Set to true to use the CI_JOB_TOKEN for authentication within a GitLab CI/CD environment. | false |
| 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. | :tada: This issue has been resolved in version ${nextRelease.version} :tada:\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. | - |
| retryLimit | The maximum number of retries for failing HTTP requests. | 3 |

#### assets

Can be a glob or and Array of
globs and Objects 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 link types). 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 |
| packageName | This is only applied if target is set to generic_package. It defines the package name (:package_name) to upload asset file to. More information could be found at Publish a package | release |
| 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 Strings 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.

##### assets examples

'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.

#### successComment

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 Objects with hash, subject, body message and author. |
| releases | Array with a release Objects 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. |

#### successCommentCondition

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 Objects with hash, subject, body message and author. |
| releases | Array with a release Objects 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. |

##### successCommentCondition example

- 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

#### failComment

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. |

##### failComment example

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

#### failCommentCondition

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 Objects with hash, subject, body message and author. |
| releases | Array with a release Objects 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. |

##### failCommentCondition example

- 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

Compatibility

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.

$3

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.

#### Why?

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 https://github.com/semantic-release/gitlab/pull/184, which is available in version 6.0.7` and beyond.