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.
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/relctl2. 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 publishrelease 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:orBREAKING-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 arenovate/ordependabot/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.
Work lands on dev; the version is written down in CHANGELOG.md and visible in review:
- Every push to
devrunsrelctl release create --prereleaseand publishes a candidateX.Y.Z-rc.N. - To release, open a pull request
dev→mainthat dates the topmost heading (## 1.4.0 — 2026-10-02). 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.- Merge with a merge commit, never a squash. The push to
mainrunsrelctl release createand publishesX.Y.Z. relctl release forwardbringsmainback intodev.
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 |
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 changelogdefault_branch is the former name of production_branch and is still read.
Priority: command-line flag > .relctl.yaml > built-in default.
| 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.
- 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 aBREAKING CHANGE:footer is major,featis minor,fixand other types are patch. Squash-merged history only; the repository needs full history (fetch-depth: 0). - calver:
YYYYMM.D.N(for example202611.2.1): year and month, day of the month, and the number of the release that day. Calculated from local git tags, needsfetch-depth: 0. - changelog: the topmost
## X.Y.Z — YYYY-MM-DDheading of the changelog. Strict format: nov, no suffix, a real date. An undated heading is not released, and the release is idempotent.
- Documentation: CLI reference, version schemes, release flows
- Migrating from awesome-ci, including a runbook an AI agent can follow
- relctl-action: setup action and reusable workflows
Please file an issue in this repository's issue tracker.
relctl is licensed under the Apache License, Version 2.0. See LICENSE.
