release

README

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

Documentation

Overview

Package release implements the gitlab-release command. It provides functions to sync tags in your git repository and a changelog in Keep a Changelog format with releases of your GitLab project.

Index

• func DeleteAllExcept(config *Config, client *gitlab.Client, releases []Release) errors.E
• func Sync(config *Config) errors.E
• func Upsert(config *Config, client *gitlab.Client, release Release, releasedAt *time.Time, ...) errors.E
• type Config
• type Package
• type Release
• type Tag

Functions

func DeleteAllExcept

func DeleteAllExcept(config *Config, client *gitlab.Client, releases []Release) errors.E

DeleteAllExcept deletes all releases which exist in the GitLab project but are not listed in releases.

func Sync

func Sync(config *Config) errors.E

Sync syncs tags in a git repository and a changelog in Keep a Changelog format with releases of a GitLab project. It creates any missing release, it updates existing releases, and it deletes and releases which do not exist anymore.

func Upsert

func Upsert(
	config *Config, client *gitlab.Client, release Release, releasedAt *time.Time,
	milestones []string, packages []Package, images []string,
) errors.E

Upsert creates or updates a release for the GitLab project given release information, milestones associated with the release, packages associated with the release, and Docker images associated with the release.

Types

type Config

type Config struct {
	ChangeTo  kong.ChangeDirFlag `` /* 324-byte string literal not displayed */
	Version   kong.VersionFlag   `help:"Show program's version and exit."                    short:"V"`
	Project   string             `` /* 229-byte string literal not displayed */
	BaseURL   string             `` /* 354-byte string literal not displayed */
	Token     string             `` /* 324-byte string literal not displayed */
	Changelog string             `` /* 324-byte string literal not displayed */
	NoCreate  bool               `help:"Only update or remove releases, do not create them." short:"U"`
}

Config provides configuration. It is used as configuration for Kong command-line parser as well.

type Package

type Package struct {
	ID      int
	Generic bool
	WebPath string
	Name    string
	Version string
	Files   []string
}

Package describes a GitLab project's package. Generic packages have files which are listed directly, while non-generic packages have a web path to which we just link.

See: https://docs.gitlab.com/ee/user/packages/package_registry/

See: https://docs.gitlab.com/ee/user/packages/generic_packages/index.html

type Release

type Release struct {
	Tag     string
	Changes string
	Yanked  bool
}

Release holds information about a release extracted from a Keep a Changelog changelog.

type Tag

type Tag struct {
	Name string
	Date time.Time
}

Tag holds information about a git tag.