# Release Construction and Publication

## Image identity

Each production image must correlate to one source revision and include OCI version, revision, creation-time, source, title, and description labels.

Release tags:

- `vX.Y.Z`: immutable release
- `git-<12-character-sha>`: immutable revision identity
- `latest`: optional convenience pointer; never recommended for controlled deployment

## Build locally

```bash
scripts/release-image.sh --version v0.1.0 --platforms linux/amd64
```

## Publish multi-architecture images

Authenticate to the registry using a scoped token, then:

```bash
docker login gitea.skeletonworks.online
scripts/release-image.sh --version v0.1.0 --push
```

The default published platforms are `linux/amd64,linux/arm64`. Both must successfully compile and load the native `better-sqlite3` dependency. If a target cannot pass build and smoke tests, omit it and state that explicitly in release notes.

## Release checklist

1. Clean checkout of the intended commit.
2. Governance, schema, frontend, backend, and browser suites pass.
3. Production image builds without local dependencies.
4. Missing-key startup fails; configured startup becomes healthy.
5. Root UI, `/api/health`, and published deep-link refresh return correctly.
6. Fresh first-run administrator setup passes with no default credentials.
7. Restart preserves data.
8. Online backup, checksum verification, destructive restore, and marker recovery pass.
9. Upgrade and rollback drill passes with pinned images and matching database backup.
10. Public source archive and container image are anonymously downloadable.
11. Release notes list image digests, architectures, known limitations, and upgrade instructions.
12. Tag and push only after explicit release approval.

Registry authentication is required only for publishing. Consumers must not require credentials for a public release; if the Gitea package cannot be pulled anonymously, publish the identical digest to a supported public registry and use it in public installation examples.