relctl

Description: relctl is a provider-agnostic release management CLI for CI/CD pipelines. It supports two versioning schemes – SemVer and CalVer – and integrates with GitHub, GitHub Enterprise, GitLab, and Jenkins.

• Technology stack: Go, Cobra CLI
• Status: Stable
• Supported environments:
  • GitHub & GitHub Enterprise (GitHub Actions)
  • GitLab (GitLab CI)
  • Jenkins Pipelines
• Versioning schemes: SemVer (branch-prefix driven) · CalVer (date-based, git-tag driven)

Getting Started

Download the latest release and add it to your PATH, or use the layer87-labs/relctl-action in GitHub Actions.

Versioning Schemes

SemVer (default)

relctl derives the SemVer bump level from the source branch name:

Branch prefix	Bump
bugfix/, fix/, patch/, dependabot/	Patch
feature/, feat/, minor/	Minor
major/	Major

CalVer

Format: YYYY.MM.DD.N – e.g. 2026.06.01.3

• YYYY.MM.DD – current date in UTC
• N – monotonically increasing counter per day, 1-based

N is calculated exclusively from local Git tags – no SCM API call, fully provider-agnostic. relctl lists all tags matching YYYY.MM.DD.* for today and sets N to max(N) + 1 (or 1 if no tag exists yet).

Prerequisite: the repository must be checked out with full tag history (fetch-depth: 0). This is already a general relctl requirement.

Configuration

.relctl.yaml (repo-level config file)

Place a .relctl.yaml in your repository root to set project-wide defaults:

version_scheme: calver   # semver (default) | calver
default_branch: main

The file is optional. When absent, relctl behaves exactly as before (SemVer, main).

Priority: --version-scheme flag > .relctl.yaml > built-in default (SemVer)

CLI Flags

Flag	Scope	Description
--config <path>	relctl, release	Override config file path (default: .relctl.yaml)
--version-scheme <scheme>	release	semver or calver; overrides config file

Usage

SemVer release (existing workflow, unchanged)

# After merging a PR – relctl reads the PR branch and GitHub API
relctl release create
relctl release publish --release-id "$RELCTL_RELEASE_ID" --asset "file=dist/binary"

CalVer release via config file

# .relctl.yaml
version_scheme: calver

# No branch prefix or PR context required
relctl release create
# → e.g. 2026.06.01.1

relctl release publish --release-id "$RELCTL_RELEASE_ID" --asset "file=dist/binary"

CalVer release via flag (no config file needed)

relctl release create --version-scheme calver
# → e.g. 2026.06.01.1

# Second release on the same day (git tag 2026.06.01.1 already exists)
relctl release create --version-scheme calver
# → 2026.06.01.2

Dry-run (preview version without creating a release)

relctl release create --version-scheme calver --dry-run
# Would create new release with version: 2026.06.01.1

GitHub Actions example

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # required: full tag history for N calculation

- name: Create CalVer release
  run: relctl release create --version-scheme calver
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Examples

More examples are available in the examples section of the documentation.

Frequently Asked Questions

See the Q&A section.

Getting Help

Please file an issue in this repository's Issue Tracker.

Community

• Contributing
• Code of Conduct
• Security Policy

License

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

Credits

• SemVer
• CalVer
• Cobra CLI
• go-git