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.9.0
    # 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.9.0'
    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.

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.

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.

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:

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:

Example

include:
  # main template
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel@3.9.0
  # Vault variant
  - component: gitlab.com/to-be-continuous/semantic-release/gitlab-ci-semrel-vault@3.9.0
    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