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.10.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.10.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:lts-slim
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)	`/^(master
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: