How Mint works

Mint separates release intent from the evidence that makes it safe to act on that intent. Its state lives with your repository and trusted GitHub Actions runs.

The release lifecycle

1. Version source. Serialize version allocation on the current default-branch head. Each untagged first-parent source commit receives an immutable strict SemVer tag.
2. Build once. Your trusted producer builds the application and uploads a mint-candidate artifact containing mint-candidate.json.
3. Register eligibility. Mint authenticates the completed producer run and its archive digest, then records source, version, build configuration, and immutable artifact identity.
4. Select per environment. Policy chooses latest-following or an exact target. Prerequisites must have verified the complete selected artifact.
5. Freeze intent. Reviewed releases wait for current-head checks and independent human approval. Mint freezes the artifact and runtime configuration together.
6. Deploy and verify. The project adapter consumes the frozen intent without rebuilding, reports start, and supplies exact verification evidence.
7. Record and report. Verified history advances. Mint reports on the original PR and, if configured, publishes the canonical GitHub Release.

Artifact identity

A readable tag such as sandbox is an optional alias. The selected artifact is an immutable digest. For a multi-component application, artifact.members includes every component's reference, digest, and build configuration; the top-level digest fingerprints the complete bundle.

The adapter must deploy and verify every member. A successful API deployment does not prove that the accompanying worker or frontend is correct.

Build configuration identifies how the artifact was made. configuration_sha256 separately identifies the runtime configuration approved for an environment. The same artifact can be deployed with different reviewed runtime configuration without rebuilding it.

State and concurrency

Shared environments have separate durable journals. The legacy production environment uses mint-release-state; other names use mint-release-state-<environment>. A component policy uses mint-release-state.<component>.<environment> for every environment, so components never share history or fences. Each environment retains a fence while a deployment is in flight or its outcome is uncertain.

An uncertain outcome cannot be cleared by dispatching another deployment or merely observing the runtime. Explicit reconciliation checks fresh trusted evidence against the frozen intent or previous baseline.

Local scope stores private machine observations. It cannot advance shared deployment history or satisfy a shared environment's prerequisite.

What belongs to your application

Mint owns version identity, release state, reviewed selection, and evidence validation. Your project owns Docker/package builds, registry authentication, artifact retention, deployment, runtime verification, cloud resources, and infrastructure permissions.

Basic mint release publish resolves a version, writes .version, creates or reuses the Git tag, and creates or reuses a GitHub Release. That is a release-state publishing command, not the entire environment controller. It does not deploy an application.

Publication-only projects

Schema 2 supports mode: artifact and mode: package alongside mode: deployment. Publication-only environments describe publication intent and keep the project's existing publication implementation. Runtime operations are rejected; no fake deployment baseline is required.

For deployment mode, at most one shared environment can have publish: true. Its verified release is canonical; other environments deploy without independently publishing the same version.