release-tools

A small installed CLI for standardizing GoReleaser-based release workflows across repositories.

release-tools keeps project-specific build config in each repository while moving repeatable release behavior into one command on PATH.

It is intended for Go, shell, and documentation/toolkit projects that publish with GoReleaser on Codeberg, Gitea, Forgejo, GitHub, or GitLab.

Overview

GoReleaser still owns builds, checksums, archives, and release asset publishing. release-tools adds the workflow around it:

• stable commands for checking, snapshotting, publishing, and generating notes
• repo-local .release-tools.env configuration with environment overrides
• a shared RELEASE_TOKEN environment token contract
• forge-aware token mapping for GoReleaser
• release notes generation from NEWS.md
• optional release body patching after publish
• safe publish-tag releases from a clean clone of the exact tag

Consumer repositories install the CLI once and run release-tools directly from the project root. They should not copy release helper scripts or use this repo's Makefile as a release frontend.

Requirements

Consumer repositories need:

• the release-tools binary installed on PATH
• GoReleaser available on PATH or through GORELEASER_BIN
• Docker, Podman, Cosign, or another configured signing command when the project-owned GoReleaser config uses container image or image-signing pipes
• Helm available on PATH when RELEASE_ARTIFACTS includes charts
• a repo-local .release-tools.env
• a project-owned .goreleaser.yaml
• NEWS.md when release notes are generated from a notes source

Maintainers of this repository also need Go 1.26, Make, and Podman for the container verification path.

Install Cosign from a trusted package source, or follow the verified install examples in docs/cosign-installation.md.

Installation

Download the matching release binary from Codeberg and place it in a directory on PATH.

Linux amd64 example:

RELEASE_TOOLS_VERSION=vX.Y.Z
version="${RELEASE_TOOLS_VERSION#v}"
mkdir -p "$HOME/.local/bin"
curl -fsSL -o "$HOME/.local/bin/release-tools" \
 "https://codeberg.org/rch/release-tools/releases/download/${RELEASE_TOOLS_VERSION}/release-tools_${version}_linux_amd64"
chmod +x "$HOME/.local/bin/release-tools"

Published binary names use this shape:

release-tools_<version>_<os>_<arch>

Supported assets:

• release-tools_X.Y.Z_linux_amd64
• release-tools_X.Y.Z_darwin_amd64
• checksums.txt

Quick Start

Add .release-tools.env to the repository that will use release-tools:

RELEASE_PROJECT=mycli
RELEASE_FORGE=codeberg
RELEASE_OWNER=myowner
RELEASE_NOTES_SOURCE=NEWS.md
RELEASE_NOTES_MODE=news-md
RELEASE_BODY_MODE=patch
GORELEASER_CONFIG=.goreleaser.yaml

The consuming repository also owns its .goreleaser.yaml and NEWS.md. Set RELEASE_NOTES_MODE=news-md for Markdown headings such as ## v1.2.3 - 2026年07月02日, or RELEASE_NOTES_MODE=gnu-news for GNU-style release headings such as * Noteworthy changes in release 1.2.3 (2026年07月02日).

Run local checks from the consumer repository root:

release-tools version
release-tools tools-check
release-tools doctor
release-tools check
release-tools snapshot
release-tools notes v1.2.3

Publish an existing tag with an available token:

release-tools publish-tag v1.2.3

Publishing requires RELEASE_TOKEN, the native GoReleaser token variable for the selected forge, or environment-only RELEASE_TOKEN_FILE pointing at a local token file.

Validation commands (check and snapshot) do not read token files and strip release-token variables before invoking GoReleaser.

Commands

Supported completion shells are bash, zsh, fish, and powershell:

release-tools completion bash
release-tools completion zsh
release-tools completion fish
release-tools completion powershell

Configuration

Consumer repositories configure release-tools with .release-tools.env and environment overrides. The Quick Start example shows the common minimum shape.

The canonical public contract for supported keys, environment-only variables, token resolution, release-notes modes, artifact classes, Helm chart behavior, release manifests, and container-image preflights is docs/usage.md.

Examples And Docs

Ready-to-copy consumer starting points:

• examples/.release-tools.env
• examples/chart-release.env
• examples/forgejo-release.yml

Binary-oriented projects can copy examples/.release-tools.env; chart-enabled projects can copy examples/chart-release.env. Copy the chosen file into the consumer repository as .release-tools.env, or set RELEASE_CONFIG_FILE explicitly when using another file name.

Documentation:

• docs/README.md: docs index
• docs/usage.md: consumer integration contract
• docs/release-procedures.md: scenario-based release procedures for binaries, containers, and Helm charts
• docs/self-release.md: maintainer self-release procedure for this repository
• docs/agent-release-flow.md: release-flow rationale and maintainer/agent notes
• docs/cosign-installation.md: verified Cosign install examples
• docs/future-work.md: deferred ideas and intentionally out-of-scope directions

Maintainer Workflow

The root Makefile is for maintainers working on this repository. It is not part of the consumer integration contract.

Common maintainer commands:

make verify
make container-test
make helm-registry-test
make helm-oci-signing-test
make helm-provenance-test
make codeberg-smoke-test
make build
make check
make snapshot
make clean

Testing

Run the local verification suite:

make verify

Run the same checks inside the dev container:

make container-test

The dev-container helper uses Podman's keep-id user namespace so generated files remain writable by the host user on rootless Podman setups.

The dev container verifies pinned SHA-256 checksums before installing downloaded Go, GoReleaser, Helm, and Cosign release artifacts.

Run Podman-backed Helm registry smoke tests against local Zot and ChartMuseum containers:

make helm-registry-test

Run a Podman-backed Helm OCI signing smoke test against local Zot. This builds the current CLI, generates a temporary Cosign key pair, signs the pushed chart by digest, and verifies the signature from a clean environment:

make helm-oci-signing-test

This target requires a trusted cosign on PATH; the dev container includes Cosign for containerized verification. See Requirements for local host install guidance.

Run a disposable GPG-backed Helm provenance smoke test. This builds the current CLI, generates a temporary signing key, runs chart-enabled release-tools snapshot, and verifies the signed chart with helm verify:

make helm-provenance-test

Run the live Codeberg smoke test against rch/release-tools-smoke with a token that can push to that repository and create releases. The smoke verifies release body patching and manifest asset upload. Package-registry access is optional and enables the Helm upload portion of the smoke test. When it runs in the dev container, the token is mounted at container run time and kept out of the image build context. The host needs realpath for token-path validation:

make codeberg-smoke-test

For focused CLI error-message checks, use:

scripts/test-errors

Self-Release

release-tools releases itself with the release-tools CLI. The root Makefile is only used for maintainer verification and for building the current local binary before publish. Follow docs/self-release.md for the canonical self-release procedure.

License

This project is licensed under the MIT License. See LICENSE for details.