semantic-release/gitlab

@semantic-release/gitlab

semantic-release plugin to publish a GitLab release.

Install

$ npm install @semantic-release/gitlab -D

Usage

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

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

Configuration

GitLab authentication

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:

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

Environment variables

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:[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

Options

assets

Can be a glob or and Array of globs and Objects with the following properties:

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:

successCommentCondition

The success comment condition is generated with Lodash template. The following variables are available:

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:

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:

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.

Breaking changes in 14.0

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.