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


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

  - 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.


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:


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
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:

See exec verifyConditionsCmd.

Parameters: none

See exec verifyReleaseCmd.


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

See exec prepareCmd.


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

See exec publishCmd.


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

See exec successCmd.


  1. Last release version
  2. next release version

See exec failcmd.


  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