Skip to content

GitLab CI template for semantic-release

This project implements a generic GitLab CI template for semantic-release.

It provides several features, usable in different modes (by configuration).

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/semantic-release'
    ref: '2.2.0'
    file: '/templates/gitlab-ci-semrel.yml'

Global configuration

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

Name description default value
SEMREL_IMAGE The Docker image used to run semantic-release node:lts
🔒 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
SEMREL_CONFIG_DIR directory containing your semantic-release configuration .
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:

Variables

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

Name description default value
SEMREL_CHANGELOG_ENABLED Add the @semantic-release/changelog plugin which will commit a changelog file in the repository if set to true. none
SEMREL_CHANGELOG_FILE changelogFile @semantic-release/changelog option. none (use the plugin default value which is CHANGELOG.md).
SEMREL_CHANGELOG_TITLE changelogTitle @semantic-release/changelog option. You might want to use markdown format (for example # MyApp Changelog). none
SEMREL_DRY_RUN Activate the dryRun semantic-release option if present. none
SEMREL_AUTO_RELEASE_ENABLED When set to true the job start automatically. When not set (default), the job is manual. none
SEMREL_TAG_FORMAT tagFormat semantic-release option. ⚠ī¸ don't forget to double the $ character so it is not interpreted by GitLab. $${version}
SEMREL_HOOKS_DIR Hook scripts folder. .
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

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 (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 🔒):

  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: $ -> $$).

Gitlab compatibility

ℹī¸ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11