Skip to content
layer87-labsPublic

About

Release Control - CLI tool for managing GitHub releases and pull requests in CI/CD pipelines

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

relctl: release control for CI/CD

Latest release Build (dev) Go version Go Report Card License: Apache-2.0

relctl

relctl is a release management CLI for CI/CD pipelines. It works out the next version of your project, creates the GitHub release and keeps your pipeline free of release boilerplate. It is the successor of awesome-ci; see the migration guide.

  • Source control: GitHub and GitHub Enterprise (GitLab as source control is not supported; open an issue if you need it).
  • CI system: GitHub Actions and Jenkins are detected automatically. Any other pipeline (including GitLab CI) connects once with relctl connect github.
  • Four ways to get the version: branch prefix, Conventional Commits, date, or a reviewed CHANGELOG.md.

Quick start

1. Install. In GitHub Actions use relctl-action, which installs a verified binary (see the example below). Elsewhere, download the release asset and check it against sha256sum.txt (Linux amd64 shown; asset names are relctl_<version>_<os>-<arch>):

VERSION=2.11.0   # see https://github.com/layer87-labs/relctl/releases/latest
BASE=https://github.com/layer87-labs/relctl/releases/download/$VERSION
curl -fsSLO "$BASE/relctl_${VERSION}_linux-amd64"
curl -fsSLO "$BASE/sha256sum.txt"
grep " relctl_${VERSION}_linux-amd64\$" sha256sum.txt | sha256sum -c -
install -m 0755 "relctl_${VERSION}_linux-amd64" /usr/local/bin/relctl

2. Run the three commands that matter. All of them read the token from GITHUB_TOKEN:

relctl pr info                                                  # on a pull request: the version it would release
relctl release create --merge-sha "$GITHUB_SHA"                 # on main: compute the version, create a draft release
relctl release publish --release-id "$RELCTL_RELEASE_ID" \
  --asset "file=dist/app"                                       # upload assets and publish

release create exports RELCTL_VERSION and RELCTL_RELEASE_ID for the following steps. Add --dry-run to preview. In GitHub Actions:

# .github/workflows/release.yaml
name: Release
on:
  push:
    branches: [main]

permissions:
  contents: write        # create and publish releases
  pull-requests: write   # relctl posts a help comment on pull requests

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - uses: layer87-labs/relctl-action@v1
        with: { github-token: "${{ secrets.GITHUB_TOKEN }}" }
      - id: release
        run: relctl release create --merge-sha ${{ github.sha }}
        env: { GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }
      # ... build your artifacts, use ${{ steps.release.outputs.RELCTL_VERSION }} ...
      - run: relctl release publish --release-id ${{ steps.release.outputs.RELCTL_RELEASE_ID }} --asset "file=dist/app"
        env: { GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }

Without a config file relctl uses SemVer from the branch prefix of the merged pull request:

Branch prefix Bump Example
fix/, bugfix/, patch/, dependabot/ patch 1.2.3 → 1.2.4
feat/, feature/, minor/ minor 1.2.3 → 1.3.0
major/, or any prefix ending in ! (feat!/) major 1.2.3 → 2.0.0

To override it, comment on the pull request before merging (the comment must start with the command): relctl_patch_level: major forces a bump level, relctl_version_override: 2.1.0 pins the version.

relctl also looks for a Conventional Commits breaking-change marker in the pull request and its own commits (not the merge commit, not the target branch):

  • ! right after the type or scope of the pull request title or of a commit subject: fix!: ..., fix(forms)!: .... A ! elsewhere (fix: handle foo!) does not count.
  • a BREAKING CHANGE: or BREAKING-CHANGE: footer at the start of a line in the description or in a commit message. A mention mid-sentence or in an indented line does not count, nor does anything inside a fenced code block, an HTML comment (<!-- -->) or a <details> block. The description of a renovate/ or dependabot/ pull request is not read (it quotes upstream release notes); its title and commits are.

breaking_markers in .relctl.yaml decides what a marker does when the branch prefix gives a patch or minor bump:

breaking_markers Effect
warn (default) keeps the bump; warning in the log, the run summary (GitHub Actions) and on top of the release notes
major raises the bump to major; fails if the commits of the pull request cannot be read completely
off ignores the markers

The default becomes major in relctl 3.0.0; set breaking_markers: major to get it now. Example with major: a pull request from fix/forms-trusted-proxies titled fix(forms)!: only trust configured proxies releases 1.9.1 → 2.0.0, not 1.9.2. A marker never lowers a bump. With relctl_version_override the markers are not checked. GitHub lists at most 250 commits of a pull request; with more, major fails (comment relctl_patch_level: major or relctl_version_override instead) and warn warns.

Reviewed releases (flow 3)

Work lands on dev; the version is written down in CHANGELOG.md and visible in review:

  1. Every push to dev runs relctl release create --prerelease and publishes a candidate X.Y.Z-rc.N.
  2. To release, open a pull request dev → main that dates the topmost heading (## 1.4.0 — 2026-10-02).
  3. relctl release gate --sha "$HEAD_SHA" is the required check: the heading is dated and has notes, the version is not released yet, and a candidate exists for exactly this commit.
  4. Merge with a merge commit, never a squash. The push to main runs relctl release create and publishes X.Y.Z.
  5. relctl release forward brings main back into dev.

Details: release flows. Flows 1 and 2 release on every merge to main:

Flow 1 Flow 2 Flow 3
Release every merge to main every merge to main merging a release pull request
Version from branch prefix commit messages or date CHANGELOG.md heading
version_scheme semver (default) conventional-commits, calver changelog
Good for libraries, CLIs services, apps products with deliberate releases

Configuration: .relctl.yaml

Optional. Place it in the repository root. Every key is optional:

# how the version is calculated: semver (default) | conventional-commits | calver | changelog
version_scheme: semver

# changelog scheme: the file with the "## X.Y.Z — YYYY-MM-DD" headings (default CHANGELOG.md)
changelog_file: CHANGELOG.md

# branches for `relctl release forward`
production_branch: main      # receives the releases (default: main)
development_branch: dev      # default: the default branch of the repository

# tags and releases get this prefix: "v" gives v1.2.3 (the version itself stays 1.2.3)
tag_prefix: v

# semver scheme: a breaking-change marker (fix!: or a BREAKING CHANGE: footer) on a fix/ or feat/ branch
# warn (default): keeps the bump and warns | major: raises the bump to major (default from 3.0.0) | off: ignores it
breaking_markers: major

# independently released parts of the repository (own tags, own latest release, own counter)
components:
  whisper:
    paths: ["deploy/whisper/**", "deploy/Containerfile.whisper"]
    version_scheme: calver   # components use calver or changelog

default_branch is the former name of production_branch and is still read.

Priority: command-line flag > .relctl.yaml > built-in default.

Commands

Command What it does
relctl release create compute the version and create a draft release (--prerelease for a release candidate, --dry-run to preview)
relctl release publish publish a draft release and upload assets (--asset "file=…", zip=, tgz=)
relctl release gate check that the changelog may be released (see flow 3)
relctl release forward bring the production branch back into the development branch (fast-forward or pull request)
relctl release changed --component NAME tell whether the files of a component changed since its latest release, so a pipeline builds only what changed (--component also works with release create, publish, gate and pr info)
relctl pr info version a pull request would produce
relctl parse json|yaml|version read values from JSON, YAML or version strings
relctl transform group-by group a JSON list by a key
relctl connect github store server and repository in .relctl-connection.yaml for pipelines that cannot be detected (GitLab CI with a GitHub repository, local shell). The file holds no secret; the token is read from GITHUB_TOKEN on every call and never stored

Variables are exported to the pipeline (GitHub Actions: $GITHUB_ENV and step outputs): RELCTL_VERSION (what was created; X.Y.Z-rc.N for a candidate), RELCTL_TAG (with the tag prefix), RELCTL_NEXT_VERSION (the release), RELCTL_LATEST_VERSION (never a candidate), RELCTL_RELEASE_ID (empty for a release that is already published), RELCTL_PRERELEASE, RELCTL_COMPONENT, RELCTL_CHANGED, RELCTL_PR, … RELCTL_SILENT=true switches the help comment on pull requests off.

Version schemes

  • semver (default): the bump comes from the branch prefix of the merged pull request (table above); a breaking-change marker in the pull request warns, or makes it major with breaking_markers: major.
  • conventional-commits: the bump comes from the commit messages since the last published release. feat!: or a BREAKING CHANGE: footer is major, feat is minor, fix and other types are patch. Squash-merged history only; the repository needs full history (fetch-depth: 0).
  • calver: YYYYMM.D.N (for example 202611.2.1): year and month, day of the month, and the number of the release that day. Calculated from local git tags, needs fetch-depth: 0.
  • changelog: the topmost ## X.Y.Z — YYYY-MM-DD heading of the changelog. Strict format: no v, no suffix, a real date. An undated heading is not released, and the release is idempotent.

Documentation

Getting help

Please file an issue in this repository's issue tracker.

Community

License

relctl is licensed under the Apache License, Version 2.0. See LICENSE.

Credits

About

Release Control - CLI tool for managing GitHub releases and pull requests in CI/CD pipelines

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages