@lets-release/gitlab

[lets-release][] plugin for publishing a [GitLab release][].

| Step | Description |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| verifyConditions | Verify the presence and the validity of the authentication and the [assets][] option configuration. |
| addChannels | Update a [GitLab release][]. |
| publish | Publish a [GitLab release][]. |
| success | Add a comment to each [GitLab Issue][] or Merge Request resolved by the release. |

Usage

The plugin can be configured in the [lets-release][] configuration file:

``json
{
"branches": ["main"],
"plugins": [
"@lets-release/commit-analyzer",
"@lets-release/release-notes-generator",
[
"@lets-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" }
]
}
]
]
}
`

In this example, [GitLab releases][GitLab release] will be published to the https://custom.gitlab.com instance.

Configuration

$3

The GitLab authentication configuration is required and can be set using [environment variables][].

There are three kinds of tokens, see [@gitbeaker/rest][] for details.
The personal token can be set using the GL_TOKEN or GITLAB_TOKEN environment variable.

The token must have the api scope.
If you are using the token for [remote Git repository authentication][], it must also have the write_repository scope.

Note: When running with dryRun, only the read_repository scope is required.

$3

| Variable | Description |
| ---------------------------- | ---------------------------------------------------- |
| GL_TOKEN or GITLAB_TOKEN | The personal token used to authenticate with GitLab. |
| CI_JOB_TOKEN | The GitLab CI job token. |
| CI_SERVER_URL | The GitLab endpoint. |
| CI_API_V4_URL | The GitLab API URL. |

$3

| Option | Description | Default |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| token | The GitLab personal token. | GH_TOKEN or GITHUB_TOKEN |
| oauthToken | The GitLab OAuth token. | - |
| jobToken | The GitLab CI job token. | CI_JOB_TOKEN |
| url | The GitLab server URL. | CI_SERVER_URL |
| apiUrl | The GitLab API URL. | CI_API_V4_URL |
| assets | An array of files to be uploaded to the release. See [assets][]. | - |
| positionOfOtherArtifacts | The position to add other artifact links to the GitLab Release. Can be "bottom" or "top". Default to not add any links. | - |
| mainPackageOnly | Create releases only for the main package | false |
| releaseNameTemplate | A [Lodash template][] to customize the gitlab release's name | ${nextRelease.tag} |
| releaseBodyTemplate | A [Lodash template][] to customize the gitlab release's body | ${nextRelease.notes} |
| commentOnSuccess | Use this as a condition for when to comment on issues or pull requests. See [commentOnSuccess][] | true |
| successComment | The comment to be added to each issue and pull request resolved by the release. Set to false to disable commenting on issues and pull requests. See [successComment][]. | generate by [getSuccessComment][] function |
| successLabels | The [labels][] to be added to each issue and pull request resolved by the release. See [successLabels][]. | - |
| milestones | An array of milestone titles to be associated to the release. See [GitLab Release API][]. | - |

#### assets

Can be a [glob][], an Array of [globs][glob], or an Object with the following properties:

| Property | Description | Default |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| path | Required, unless url is set. A [glob][] to identify the files to be uploaded. | - |
| url | As an alternative to setting path, this provides the ability to add links to releases, e.g., URLs to container images. | - |
| label | A short description of the file displayed on the GitLab release. Ignored if path matches more than one file. | File name extracted from the path. |
| type | The asset type displayed on the GitLab release. Can be runbook, package, image and other (see official documents on [release assets][]). | other |
| filepath | A file path 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. | - |
| 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 or hidden (see official documents on [generic packages][generic package]). | default |

Each entry in the assets Array is globed individually.
A [glob][] can be a String ("dist//.js" or "dist/mylib.js") or an Array of Strings that will be globed together (["dist/", "!/.css"]).

If a directory is configured, all the files under this directory and its subdirectories will be included.

The label for each asset is generated with [Lodash template][]. The following variables are available:

| Parameter | Description |
| ------------- | ------------------------------------------ |
| branch | The branch from which the release is done. |
| lastRelease | The last release. |
| nextRelease | The release being done. |
| commits | Array of commit Objects. |

Note: If a file matches an entry in assets, it will be included even if it also has a match in .gitignore.

##### assets examples

'dist/*.js': includes all the js files in the dist directory, but not in its subdirectories.

[['dist', '!*/.css']]: includes all the files in the dist directory and its subdirectories excluding the css files.

[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]: includes the dist/MyLibrary.js and dist/MyLibrary.css files,
and labels them MyLibrary JS distribution and MyLibrary CSS distribution in the GitLab release.

[['dist//.{js,css}', '!/.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]: includes all the js and css files in the dist directory and its subdirectories excluding the minified version,
plus the build/MyLibrary.zip file and labels it MyLibrary in the GitLab release.

#### commentOnSuccess

A boolean or a function that returns a boolean or Promise to determine whether to comment on issues and merge requests on success. The following variables are available:

| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| branch | The branch from which the release is done. |
| lastRelease | The last release. |
| nextRelease | The release being done. |
| commits | Array of commit Objects. |
| artifacts | Array of artifact Objects. |
| issue | A [GitLab API Merge Request object][] for merge requests related to a commit, or [GitLab API Issue object][] for issues. |

#### successComment

The message for the issue comments is generated with [Lodash template][]. The following variables are available:

| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| branch | The branch from which the release is done. |
| lastRelease | The last release. |
| nextRelease | The release being done. |
| commits | Array of commit Objects. |
| artifacts | Array of artifact Objects. |
| issue | A [GitLab API Merge Request object][] for merge requests related to a commit, or [GitLab API Issue object][] for issues. |

#### successLabels

Each label name is generated with [Lodash template][]. The following variables are available:

| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| branch | The branch from which the release is done. |
| lastRelease | The last release. |
| nextRelease | The release being done. |
| commits | Array of commit Objects. |
| artifacts | Array of artifact Objects. |
| issue` | A [GitLab API Merge Request object][] for merge requests related to a commit, or [GitLab API Issue object][] for issues. |

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.

[environment variables]: #environment-variables
[assets]: #assets
[commentOnSuccess]: #commentonsuccess
[successComment]: #successcomment
[successLabels]: #successlabels

[lets-release]: ../../
[getSuccessComment]: ../../libs/git-host/src/helpers/getSuccessComment.ts

[GitLab release]: https://docs.gitlab.com/ee/user/project/releases/
[GitLab Issue]: https://docs.gitlab.com/ee/user/project/issues/
[remote Git repository authentication]: https://github.com/lets-release/lets-release/blob/master/docs/usage/ci-configuration.md#authentication
[labels]: https://docs.gitlab.com/ee/user/project/labels.html#labels
[GitLab Release API]: https://docs.gitlab.com/ee/api/releases/#create-a-release
[release assets]: https://docs.gitlab.com/ee/user/project/releases/#release-assets
[permanent links]: https://docs.gitlab.com/ee/user/project/releases/#permanent-links-to-release-assets
[project upload]: https://docs.gitlab.com/ee/api/projects.html#upload-a-file
[generic package]: https://docs.gitlab.com/ee/user/packages/generic_packages/
[GitLab API Merge Request object]: https://docs.gitlab.com/ee/api/merge_requests.html#get-single-mr
[GitLab API Issue object]: https://docs.gitlab.com/ee/api/issues.html#single-issue
[which is the current major version and previous two major versions]: https://about.gitlab.com/support/statement-of-support.html#version-support
[@gitbeaker/rest]: https://github.com/jdalrymple/gitbeaker/tree/main/packages/rest#api-client
[Lodash template]: https://lodash.com/docs#template
[glob]: https://github.com/isaacs/node-glob#glob-primer