audita/docs/release.md

Releasing Audita

The release policy owns release requirements. This runbook uses the native commands in scripts/release.sh, which invokes the module-selected ReleaseKit tool. A confirmed source tag completes the release; Woodpecker reports binary delivery separately.

Prerequisites

Use Bash and Git. The authoritative remote is origin, which must point to https://gitea.maximumdirect.net/eric/audita.git; the primary branch is main. Source publication needs no delivery credential. Woodpecker uses the existing GITEA_RELEASE_TOKEN secret for delivery.

The source-build minimum is Go 1.26.0, declared in go.mod. This minimum is required by the selected ReleaseKit dependency. Distributed executables do not require a Go installation. The selected release toolchain is Go 1.26.8, matching the current Woodpecker image and distributed runtime notices. Use that local installation for tool bootstrap, candidate validation, and release builds. Replace the installation path below with its actual directory:

export PATH="/path/to/go1.26.8/bin:$PATH"
export GOTOOLCHAIN=local
go version

Record the reported toolchain with the validation results. The release policy governs the distinction between the consumer minimum and release toolchain, support across a Go series, and versioning of minimum increases. When selecting a different release toolchain, update the CI image and applicable runtime attribution together; a newer build patch alone need not raise the minimum.

Prepare dependencies before offline candidate validation:

GOWORK=off GOTOOLCHAIN=local go mod download

If dependency preparation changes go.mod or go.sum, include those changes in the committed candidate. ReleaseKit's CLI is registered as a Go tool dependency; go mod tidy retains its dependencies and checksums. The release wrapper changes to the repository root and invokes go tool releasekit with workspace discovery and automatic toolchain downloads disabled. Go builds or reuses the selected tool from its normal build cache. Tool preparation precedes offline candidate validation.

Prepare and publish the candidate

Choose an unused version under the release policy, write docs/releases/<version>.md, and begin it with # Audita <version>. Include a short summary, relevant compatibility or upgrade instructions, and the required COPYRIGHT | LICENSE | ATTRIBUTION footer with links for the selected version. Update affected canonical documentation with behavior changes.

End each note with this footer, substituting its complete tag for <version>:

[COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/docs/oss/attribution.md)

Commit the complete candidate on main, including the release note, then push the branch first:

git push origin main

Record the candidate commit. Before publication, remote main must identify that exact commit. ReleaseKit checks this along with the clean candidate, note, version, and remote tag state.

Publish from the repository root, substituting the selected version:

bash scripts/release.sh publish VERSION

The command runs go test -mod=readonly -count=1 ./... once with module and toolchain network access disabled, builds the profile's Linux amd64 and arm64 targets, and checks the native version output. It creates an annotated tag whose message comes from the committed note, then pushes the exact tag object. A successful publication completes the source release without waiting for CI or checking artifact availability.

bash scripts/release.sh check VERSION is an optional local diagnostic. It does not inspect remote availability or publish a tag, and it is not a required step before publish, which performs its own candidate validation.

The wrapper preserves ReleaseKit's exit status: 0 means confirmed publication; 1 means a known validation or publication failure/conflict; 2 means usage, profile, or version input error; and 3 means the push outcome remains unknown.

Binary delivery

Woodpecker runs ReleaseKit's ci-deliver command for tags under refs/tags/v*. The tagged go.mod selects the ReleaseKit version, and releasekit.json supplies Audita's build and delivery settings:

• audita-<version>-linux-amd64
• audita-<version>-linux-arm64
• SHA256SUMS

Before running Go, the workflow fetches and verifies the event tag, checks it out detached, and confirms the source tree is clean. It copies the tagged go.mod and go.sum into temporary module metadata outside the checkout. Go confirms that this configuration selects ReleaseKit, then builds its CLI using an alternate -modfile. The bootstrap executable and temporary files remain outside the tagged source. The workflow runs with the selected Go 1.26.8 image, GOWORK=off, and GOTOOLCHAIN=local.

The resulting executable receives:

"$${bootstrap_dir}/releasekit" ci-deliver \
  --repo "$${CI_WORKSPACE}" \
  --commit "$${CI_COMMIT_SHA}" \
  "$${CI_COMMIT_TAG}"

The workflow maps the existing GITEA_RELEASE_TOKEN secret to RELEASEKIT_GITEA_TOKEN. The complete checked-in release note, including its licensing footer, supplies the hosted release body. Delivery runs independently after source publication; its status and logs report delivery progress or failure.

ReleaseKit handles content-aware retries and retained-artifact recovery. See the pinned publication recovery guide and delivery guide for those mechanics. A delivery failure does not undo a confirmed source release. Retry the same immutable tag after resolving the reported state; do not replace published files or a checksum manifest.

Failure and recovery

Fix validation failures in a new committed candidate, then rerun publish. After a failed push, ReleaseKit retains the local annotated tag and reports the captured authoritative endpoint and publication state. Resolve the result against that endpoint before retrying. An exact remote tag-object match, with its source available on remote main, can confirm publication. If the remote state cannot be read, the result remains unknown; do not remove or replace the tag while uncertain. Follow the pinned publication recovery guide for object-level recovery details.

A source-release success and artifact-delivery status are separate. For a partial or uncertain delivery, inspect the job output and follow the pinned delivery recovery guidance. A source or published-content correction requires a new appropriate version; leave the original tag and its contents intact.