README.md

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.3
    # 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.3'
    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
branches-ref / SEMREL_BRANCHES_REF	Regular expression pattern matching branches from which releases should happen (should match your semantic-release configuration)	$PROD_REF (global to be continuous variable)
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:

1. Last release version
2. next release version
3. next release type

prepare.sh

See exec prepareCmd.

Parameters:

1. Last release version
2. next release version
3. next release type

publish.sh

See exec publishCmd.

Parameters:

1. Last release version
2. next release version
3. release branch
4. commits count
5. current date

success.sh

See exec successCmd.

Parameters:

1. Last release version
2. next release version

fail.sh

See exec failcmd.

Parameters:

1. Last release version
2. 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 with PROD_REF environment variable)
• branches-ref to enable on branches associated with branches-ref component configuration or SEMREL_BRANCHES_REF environment variable (main or master by default as it fallbacks on PROD_REF environment variable).
• 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 ):

1. 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).
2. 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.
3. Don't forget to escape special characters (ex: $ -> $$).
4. 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.3
  # Vault variant
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel-vault@3.8.3
    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