@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

$ 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

| 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

Options

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

Gitlab

Install / Use

README