GitLab CI template for semantic-release¶

This project implements a GitLab CI/CD template to automate your versioning and release management with semantic-release, supporting one or several of the following features:

determine the next release version number,
generate the changelog,
commit any changed resource to the Git repository,
create and push the Git tag,
publish the packages (in GitLab or any other package repository of your choice),
any additional custom behavior you are able to script, triggered on the release steps.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your gitlab-ci.yml:

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel@3.8.2
    # 2: set/override component inputs
    inputs:
      changelog-enabled: true # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/semantic-release'
    ref: '3.8.2'
    file: '/templates/gitlab-ci-semrel.yml'

variables:
  # 2: set/override template variables
  SEMREL_CHANGELOG_ENABLED: "true" # ⚠ this is only an example

Global configuration¶

The semantic-release template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
`image` / `SEMREL_IMAGE`	The Docker image used to run semantic-release	`registry.hub.docker.com/library/node:latest`
`version` / `SEMREL_VERSION`	The semantic-release version to use	`latest`
`exec-version` / `SEMREL_EXEC_VERSION`	The @semantic-release/exec version to use	`latest`
`GITLAB_TOKEN`	A GitLab project access token or personal access token with `api`, `read_repository` and `write repository` scopes. This variable is mandatory and defined by `semantic-release` itself.	none
`GIT_AUTHOR_EMAIL`	A Git author email address associated with the `GITLAB_TOKEN` bot user. This is defined by `semantic-release` itself, and required if the verify-user push rules enabled for the project	none
`GIT_COMMITTER_EMAIL`	A Git committer email address associated with the `GITLAB_TOKEN` bot user. This is defined by `semantic-release` itself, and required if the verify-user push rules enabled for the project	none
`config-dir` / `SEMREL_CONFIG_DIR`	directory containing your semantic-release configuration	`.`
`required-plugins-file` / `SEMREL_REQUIRED_PLUGINS_FILE`	An optional file for additional npm packages to install	`semrel-required-plugins.txt`

Jobs will extract required plugin packages from discovered configuration. If your configuration needs additional packages, add them, one per line, to SEMREL_REQUIRED_PLUGINS_FILE file. Each line must be a valid npm install package argument.

Jobs¶

`semantic-release` job¶

This job runs semantic-release in ci mode.

This template supports all semantic-release configuration files except for release.config.js and custom CLI arguments.

If no configuration is found, the template will generate one with the following options:

debug: true if the $TRACE variable is set, false otherwise
dryRun: true if the $SEMREL_DRY_RUN variable is set, false otherwise
tagFormat: see $SEMREL_TAG_FORMAT variable
plugins:
- @semantic-release/commit-analyzer
- @semantic-release/release-notes-generator
- @semantic-release/gitlab
- @semantic-release/git
- optional @semantic-release/changelog if SEMREL_CHANGELOG_ENABLED is set to true
- optional @semantic-release/exec if any hook script is found (see hook scripts)
branches: master

Variables¶

As specified in the previous chapter, these variables are only used to generated a .releaserc when no configuration is found in the repository.

Input / Variable	Description	Default value
`changelog-enabled` / `SEMREL_CHANGELOG_ENABLED`	Add the @semantic-release/changelog plugin which will commit a changelog file in the repository if set to `true`.	none
`changelog-file` / `SEMREL_CHANGELOG_FILE`	changelogFile @semantic-release/changelog option.	none (use the plugin default value which is `CHANGELOG.md`).
`changelog-title` / `SEMREL_CHANGELOG_TITLE`	changelogTitle @semantic-release/changelog option. You might want to use markdown format (for example `# MyApp Changelog`).	none
`dry-run` / `SEMREL_DRY_RUN`	Activate the dryRun semantic-release option if present.	none
`auto-release-enabled` / `SEMREL_AUTO_RELEASE_ENABLED`	When set to `true` the job start automatically. When not set (default), the job is manual.	none
`tag-format` / `SEMREL_TAG_FORMAT`	tagFormat semantic-release option. don't forget to double the `$` character so it is not interpreted by GitLab.	`$${version}`
`hooks-dir` / `SEMREL_HOOKS_DIR`	Hook scripts folder.	`.`
`commit-message` / `SEMREL_COMMIT_MESSAGE`	Add a custom commit message based on semantic-release/git option.	none (uses semantic-release default commit message)
`release-disabled` / `SEMREL_RELEASE_DISABLED`	Disable this job.	none

Hook scripts¶

The generated .releaserc will include the @semantic-release/exec plugin if any of the following scripts is found in the $SEMREL_HOOKS_DIR folder:

verify-conditions.sh¶

See exec verifyConditionsCmd.

Parameters: none

verify-release.sh¶

See exec verifyReleaseCmd.

Parameters:

Last release version
next release version
next release type

prepare.sh¶

See exec prepareCmd.

Parameters:

Last release version
next release version
next release type

publish.sh¶

See exec publishCmd.

Parameters:

Last release version
next release version
release branch
commits count
current date

success.sh¶

See exec successCmd.

Parameters:

Last release version
next release version

fail.sh¶

See exec failcmd.

Parameters:

Last release version
next release version

Signing release commits with GPG¶

For an introduction on commit signing, see GitLab documentation.

To make semantic-release sign its commits, use the following variable.

Input / Variable	Description	Default value
`SEMREL_GPG_SIGNKEY`	Path to the GPG signkey exported with `gpg --armor --export-secret-key` Declare as a masked project variable of File type.	none

`semantic-release-info` job¶

This job (disabled by default) runs semantic-release with dry-run mode in .pre stage to save the following variables as dotenv artifact making them available for the next pipeline stages:

SEMREL_INFO_LAST_VERSION: latest released version
SEMREL_INFO_NEXT_VERSION: next release version (based on actual commits and comments)
SEMREL_INFO_NEXT_VERSION_TYPE: next release type (major|minor|patch)

SEMREL_INFO_NEXT_VERSION and SEMREL_INFO_NEXT_VERSION_TYPE wont be available when semantic-release commits analysis determine that no release will be performed.

This job can be enabled by defining the SEMREL_INFO_ON variable:

prod to enable on production branch only (main or master by default)
protected to enable on protected references
all to enable on all Git references. Beware that this job requires the GITLAB_TOKEN variable so you must unprotect it (this will make privilege escalation possible from developer to maintainer).

Secrets management¶

Here are some advices about your secrets (variables marked with a ):

Manage them as project or group CI/CD variables:
- masked to prevent them from being inadvertently displayed in your job logs,
- protected if you want to secure some secrets you don't want everyone in the project to have access to (for instance production secrets).
In case a secret contains characters that prevent it from being masked, simply define its value as the Base64 encoded value prefixed with @b64@: it will then be possible to mask it and the template will automatically decode it prior to using it.
Don't forget to escape special characters (ex: $ -> $$).
You can also manage secrets using Vault variant

Variants¶

The Docker template can be used in conjunction with template variants to cover specific cases.

Vault variant¶

This variant allows delegating your secrets management to a Vault server.

Configuration¶

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable	Description	Default value
`TBC_VAULT_IMAGE`	The Vault Secrets Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest`
`vault-base-url` / `VAULT_BASE_URL`	The Vault server base API url	none
`vault-oidc-aud` / `VAULT_OIDC_AUD`	The `aud` claim for the JWT	`$CI_SERVER_URL`
`VAULT_ROLE_ID`	The AppRole RoleID	must be defined
`VAULT_SECRET_ID`	The AppRole SecretID	must be defined

Usage¶

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Parameter	Description
`secret_path` (path parameter)	this is your secret location in the Vault server
`field` (query parameter)	parameter to access a single basic field from the secret JSON payload

Example¶

include:
  # main template
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel@3.8.2
  # Vault variant
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel-vault@3.8.2
    inputs:
      vault-base-url: "https://vault.acme.host/v1"
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"

variables:
  # Secrets managed by Vault
  GITLAB_TOKEN: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/semantic-release/token?field=group-access-token"
  # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

GitLab CI template for semantic-release¶

Usage¶

Use as a CI/CD component¶

Use as a CI/CD template (legacy)¶

Global configuration¶

Jobs¶

semantic-release job¶

Variables¶

Hook scripts¶

verify-conditions.sh¶

verify-release.sh¶

prepare.sh¶

publish.sh¶

success.sh¶

fail.sh¶

Signing release commits with GPG¶

semantic-release-info job¶

Secrets management¶

Variants¶

Vault variant¶

Configuration¶

Usage¶

Example¶

`semantic-release` job¶

`semantic-release-info` job¶