Forelead handbook

Appearance

Release channels ​

Forelead instances pull updates. Forelead never pushes one. A release is a signed list (the manifest) of every image by digest, the database migration level and the pinned versions from forelead.env. An instance refuses anything unsigned, signed by the wrong identity, older than what it already runs, or with a failed conformance result.

In plain words ​

  • Releases are signed by one workflow. The release workflow in GitHub Actions signs the manifest and every image. Instances accept only that exact signer.
  • A person approves each release. The release environment has the owner as the only reviewer. Agents have no path to approve a release.
  • Instances check before they change anything. If verification fails, nothing is written.

What exists and what does not ​

The release tool (tools/release) can build a manifest, verify it, and write a pins file from a verified channel. Not done yet: the content-free heartbeat (off switch for self-hosted), wiring deploy/upgrade.sh to read release-pins.json, and the real image build steps in the workflow draft. Today the local stack is upgraded with deploy/upgrade.sh (see Upgrade and rollback).

Technical notes ​

  • release build makes manifest.json from forelead.env, migrations/ and image digests; the format is schema/release-manifest-v1.schema.json.
  • release verify runs cosign verify-blob on the manifest and cosign verify and verify-attestation (SBOM and SLSA provenance) on every image, pinned to the identity https://github.com/forelead-ai/platform/.github/workflows/release.yml@refs/heads/main and the GitHub Actions OIDC issuer. It needs the cosign CLI.
  • The workflow file is applied by hand because the GitHub App cannot change .github/. The full steps are in Signed release channel.

Sources ​