Automatic GitLab releases

Sync tags in your git repository and a changelog in Keep a Changelog format with releases of your GitLab project.

Features:

• Extracts description of each release entry in a changelog in Keep a Changelog format and creates or updates a corresponding GitLab release.
• Any deleted release entry in a changelog removes a corresponding GitLab release, too. But consider instead marking a release in the changelog as [YANKED].
• Automatically associates milestones, packages, and Docker images with each release.
• Makes sure your changelog can be parsed as a Keep a Changelog.
• Makes sure all release entries in your changelog have a corresponding git tag and all git tags have a corresponding release entry in your changelog.
• Can run as a CI job.

Installation

Releases page contains a list of stable versions. Each includes:

• Statically compiled binaries.
• Docker images.

You should just download/use the latest one.

The tool is implemented in Go. You can also use go install to install the latest stable (released) version:

go install gitlab.com/tozd/gitlab/release/cmd/gitlab-release@latest

To install the latest development version (main branch):

go install gitlab.com/tozd/gitlab/release/cmd/gitlab-release@main

Usage

The tool operates automatically and uses defaults which makes it suitable to run inside the GitLab CI environment. To see configuration options available, run

gitlab-release --help

You can provide some configuration options as environment variables.

The only required configuration option is the access token which you can provide with -t/--token command line flag or GITLAB_API_TOKEN environment variable. Use a personal access token or project access token with api scope and permission to manage releases (at least developer level and if you use protected tags, the token must be allowed to create protected tags, too).

The tool automatically associates:

• milestones: if the release version matches the title of the milestone; each release can have multiple milestones; each milestone can be associated with multiple releases
• generic packages: if the release version matches generic package's version all files contained inside the generic package are associated with the release
• other packages: if the release version matches package's version
• Docker images: if the release version matches the full Docker image name

Version matching is done by searching if the target string contains the version string, with and without v prefix, and with version slugified and not.

GitLab CI configuration

You can add to your GitLab CI configuration a job like:

sync_releases:
  stage: deploy

  image:
    name: registry.gitlab.com/tozd/gitlab/release/branch/main:latest-debug
    entrypoint: [""]

  script:
    - /gitlab-release ${CI_COMMIT_BRANCH:+--no-create}

  rules:
    - if: '$GITLAB_API_TOKEN && ($CI_COMMIT_BRANCH == "main" || $CI_COMMIT_TAG)'

Notes:

• Job runs only when GITLAB_API_TOKEN is present (e.g., only on protected branches) and only on the main branch (e.g., one with the latest stable version of the changelog) or when the repository is tagged. Change to suit your needs.
• Configure GITLAB_API_TOKEN as GitLab CI/CD variable. Protected and masked.
• The example above uses the latest version of the tool from the main branch. Consider using a Docker image corresponding to the latest released stable version.
• Use of -debug Docker image is currently required. See this issue for more details.
• ${CI_COMMIT_BRANCH:+--no-create} configures the tool on branch jobs to just update or remove releases. Releases are then created only on tag jobs. (GitLab runs two CI jobs when pushing a commit with a tag, a branch job and a tag job.)

Releases maintained using this tool

To see how releases look when maintained using this tool, check out these projects:

• This project itself
• gitlab-config tool
• gitlab.com/tozd/go/errors Go package
• dinit

Feel free to make a merge-request adding yours to the list.

Related projects

• Release CLI – A tool made by GitLab itself and is able to use instructions from .gitlab-ci.yml to create releases. It requires for a release to be explicitly defined through arguments which are then passed on to the API. This tool on the other hand determines everything defining a release automatically (description from a changelog, milestones, packages, Docker images). Moreover it updates existing releases as well, if their definitions change.

GitHub mirror

There is also a read-only GitHub mirror available, if you need to fork the project there.