Semantic Release GitLab CI Component¶

A GitLab CI component for semantic-release - a tool that automates the release process including version determination, changelog generation, and release publishing.

Features¶

Automated Version Management: Automatically determines next release version from commit messages
Changelog Generation: Creates and updates changelog files automatically
Plugin Ecosystem: Support for GitLab, Git, npm, and changelog plugins
Flexible Configuration: Customise release branches, plugins, and commit author information
Dry-run Support: Validate configuration without making actual releases
Bot Integration: Configure custom author and committer information for releases
Configurable Job Settings: Customise job name, stage, and container image

Usage¶

Basic Usage¶

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/semantic-release/main@latest

stages:
  - release

With Custom Configuration¶

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/semantic-release/main@latest
    inputs:
      job_name: "release"
      branches: "/^(main|master|develop)$/"
      install_changelog: true
      install_npm: true
      dry_run: false

With Custom Bot Information¶

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/semantic-release/main@latest
    inputs:
      sr_author_name: "Release Bot"
      sr_author_email: "releases@company.com"
      sr_committer_name: "Release Bot"
      sr_committer_email: "releases@company.com"

Inputs¶

Input	Description	Default
`job_name`	Name of the CI job	`"semantic-release"`
`stage`	Pipeline stage	`"release"`
`image`	Docker image for running semantic-release	`"registry.gitlab.com/niclas-zone/ctr/node:22.13.1"`
`semantic_release_version`	Version of the semantic-release npm package	`"latest"`
`branches`	Regex pattern for branches that trigger releases	`"/^(main\
`dry_run`	Execute in dry-run mode (no actual changes)	`false`
`install_gitlab`	Install @semantic-release/gitlab plugin	`true`
`install_commit_analyzer`	Install @semantic-release/commit-analyzer plugin	`true`
`install_release_notes`	Install @semantic-release/release-notes-generator plugin	`true`
`install_git`	Install @semantic-release/git plugin	`true`
`install_changelog`	Install @semantic-release/changelog plugin	`false`
`install_npm`	Install @semantic-release/npm plugin	`false`
`additional_plugins`	Comma-separated list of additional npm plugins	`""`
`use_bot_infos`	Fetch author/committer data from GitLab API	`false`
`semrel_author`	Override author name for release commits	`""`
`semrel_email`	Override author email for release commits	`""`
`sr_author_name`	Default author name for release commits	`"Semantic Release Bot"`
`sr_author_email`	Default author email for release commits	`"bot@example.dev"`
`sr_committer_name`	Default committer name for release commits	`"Semantic Release Bot"`
`sr_committer_email`	Default committer email for release commits	`"bot@example.dev"`
`install_recommended`	Automatically enable recommended plugins	`true`

Technical Workflow¶

The component extends a shared job configuration (defined as .semantic-release-common) and executes the following steps:

Installing Dependencies:
In the before_script stage, necessary packages (e.g., Git, OpenSSH, curl, jq, Node.js, and npm) are installed through the package manager.
Setting Environment Variables:
Default values for author and committer information are assigned. These can be overridden manually using semrel_author and semrel_email, or dynamically via the GitLab API if use_bot_infos is enabled.
Installing npm Packages:
Based on the defined input flags, the respective semantic-release npm packages are installed globally using npm install -g. Any additional plugins specified in additional_plugins are installed as well.
Executing Semantic Release:
In the script section, semantic-release is executed in either regular mode or dry-run mode, depending on the dry_run flag.

Example Jobs¶

Typically, the component defines two jobs: one for the actual release process and another for configuration validation.

1. Release Job¶

This job runs automatically on the main or master branch, with an option to trigger manually if needed:

semantic-release:
  extends: .semantic-release-common
  rules:
    - if: '$CI_COMMIT_BRANCH =~ /^(main|master)$/'
      when: always
    - when: manual
      allow_failure: true

2. Configuration Check Job¶

Run a dry-run to validate your configuration:

semantic-release-config-check:
  extends: .semantic-release-common
  stage: test
  variables:
    DRY_RUN: "true"
  script:
    - echo "Running Semantic Release dry-run to validate configuration..."
    - semantic-release --dry-run --no-ci
  rules:
    - when: always
  allow_failure: true

Secrets Management¶

Make sure to store a valid GitLab token (e.g., GITLAB_TOKEN) as a protected CI/CD variable. This is particularly important when use_bot_infos is enabled so that your pipeline can access the GitLab API to fetch bot information.