# Releasing Audita

The [release policy](policy/release.md) owns release requirements. This runbook
uses the native commands in [scripts/release.sh](../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](../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:

```sh
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](policy/release.md#consumer-minimum-and-release-toolchain)
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:

```sh
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](policy/release.md), 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>`:

```markdown
[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:

```sh
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:

```sh
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:

```sh
"$${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](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/publish.md)
and [delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/delivery.md)
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](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/publish.md)
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](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/delivery.md).
A source or published-content correction requires a new appropriate version;
leave the original tag and its contents intact.