Releases & Versioning

KoAkademy publishes only reviewed stable releases. Delivery has two focused responsibilities: maintain the Release Please pull request after a master merge, then publish an image and installer bundle only when that reviewed release is created.

Source event	Result
Pull request	CI validation only; no artifacts or credentials
`master` merge	Release Please creates or updates a draft release PR
Merged Release Please PR	Exact `vX.Y.Z` tag, multi-architecture GHCR image, checksummed installer bundle, published GitHub Release

Stable production releases do not use a rolling latest or manual version override. Production deployments resolve the GitHub Release asset and use its immutable GHCR digest. The separate edge channel follows the current unreleased master commit for staging and development; it is not a stable release and uses the mutable edge-frankenphp image.

Release flow

Release Please reads Conventional Commit titles from merged work and opens a reviewed PR. Merging that PR updates CHANGELOG.md, .release-please-manifest.json, and the tracked version.json version, creates the exact vX.Y.Z tag, and creates a draft GitHub Release.

The same Delivery run then:

Checks out the tag’s immutable commit and verifies its version metadata.
Builds the FrankenPHP image for linux/amd64 and linux/arm64.
Pushes ghcr.io/yukazakiri/koakademy:sha-<commit> and :vX.Y.Z.
Verifies the release tag resolves to the built digest and contains both architectures.
Publishes BuildKit SBOM/provenance and GitHub attestation.
Rewrites the release version.json to the digest, checksums the installer bundle, uploads it, and publishes the draft release.

The delivery job validates the complete asset contract before uploading: the bootstrap, operator command, Swarm files, Compose fallback, environment example, image metadata, and SHA256SUMS must all be present and match. Before announcing a release, maintainers should download the draft assets on a disposable Linux host, verify the checksum manifest, and exercise the installer against a staging domain.

The exact SemVer image tag and its digest are the deployment contract. Do not deploy a mutable alias.

Module releases

Standalone modules have a separate release step. A module tag updates the public catalog only after a registry maintainer generates and signs the matching metadata. The KoAkademy application then updates its Composer lockfile and publishes a new image before a deployed container can receive the module code.

Read Module Registry for the contributor workflow, signing boundary, Composer commands, Marketplace enablement, Swarm rollout, legacy source-tree module behavior, and rollback guidance.

Stable release assets

Every release contains:

version.json with the immutable GHCR image digest
install.sh and koakademy
swarm-stack.yml, swarm-stack-direct.yml, Caddyfile, and koakademy-app-entrypoint.sh
compose.production.yaml and default.env.production.example
SHA256SUMS

Verify downloaded files before executing them:

sha256sum --check SHA256SUMS

Required GitHub configuration

Setting	Purpose
`RELEASE_PLEASE_TOKEN`	Fine-grained token with Contents, Pull requests, and Issues read/write for Release Please
`release-automation`	Protected environment for Release Please
`container-publishing`	Protected environment for GHCR publishing and release assets

The built-in GitHub token publishes the repository’s GHCR package, attestations, and release assets. Keep both environments limited to protected branches.

Recovery and rollback

Delivery deliberately does not rebuild old releases or move image tags. If a published release has a registry or asset incident, investigate and repair it during a maintenance window with the exact tag and digest; do not make a new build overwrite an immutable tag.

Application rollback uses the prior exact image recorded by koakademy update. It never reverses database migrations automatically. Read release notes and restore the matching database backup when prior code cannot use the migrated schema.