audita/docs/release.md

Releasing Audita

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

Prerequisites

Use Bash, Git, and Go 1.25.5 or newer. 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.

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. The release wrapper separately builds the ReleaseKit version selected by go.mod into ignored bin/releasekit. It uses temporary copies of go.mod and go.sum for tool dependency preparation; that build is tool preparation, not 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 existing Go 1.25.5 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.