# Release with confidence.

Mint gives every release a clear path from source to artifact to environment. Build once, review an exact selection, and keep evidence of what actually ran.

<div class="hero-actions"><a class="button" href="https://jamesonstone.github.io/mint/integration.md">Integrate Mint →</a><a class="secondary" href="https://jamesonstone.github.io/mint/environments.md">Explore environments</a></div>

## One artifact. Any environment.

Mint is a Go CLI and GitHub Action for release state. It versions source, records trusted immutable builds, coordinates reviewed environment releases, and records verified outcomes. Your application owns the build and deployment adapters.

<div class="flow" aria-label="Release lifecycle"><span>Source</span><b>→</b><span>Build</span><b>→</b><span>Review</span><b>→</b><span>Verify</span></div>

A sandbox can use the same digest as staging or a customer demo. No environment named production is required. Each environment has its own policy and deployment history; a multi-component application moves as a complete digest bundle.

## Start here

- [How Mint works](https://jamesonstone.github.io/mint/how-it-works.md): source versions, candidates, frozen intent, and evidence.
- [Integrate Mint](https://jamesonstone.github.io/mint/integration.md): choose a release model, add policy, and connect trusted adapters.
- [Environments & sandboxes](https://jamesonstone.github.io/mint/environments.md): local versus shared scope, arbitrary names, and promotion prerequisites.
- [Semantic versioning](https://jamesonstone.github.io/mint/versioning.md): understand what increments a version and what a tag proves.
- [CHANGELOG integration](https://jamesonstone.github.io/mint/changelog.md): generate linked release notes from Conventional Commits.
- [Release PRs](https://jamesonstone.github.io/mint/release-prs.md): review the selection that will deploy.
- [Rollback & hotfix](https://jamesonstone.github.io/mint/recovery.md): recover without losing artifact identity or deployment evidence.

## Know what is proven

| Evidence | What it means |
| --- | --- |
| Source tag | A source commit has a version identity. |
| Trusted candidate | A successful build produced an eligible immutable artifact. |
| Approved Release PR | Humans approved an exact selection and runtime configuration. |
| Verified deployment | The adapter verified that exact selection in the environment. |
| Live observation | Timestamped evidence of the runtime at observation time. |

A merge, dispatch, image alias, or GitHub Release alone does not establish live runtime state.

## Read with an agent

Use [llms.txt](https://jamesonstone.github.io/mint/llms.txt) for a concise map, [llms-full.txt](https://jamesonstone.github.io/mint/llms-full.txt) for the complete guides, or the **Markdown source** link on any page. The site works without JavaScript and loads its fonts locally.


---

# 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](https://jamesonstone.github.io/mint/recovery.md#reconcile-an-uncertain-deployment) 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.


---

# Integrate Mint

Start with the smallest release model your repository needs. Add environment control when you need reviewed promotion, verified history, or recovery across environments.

## Install the CLI

Use a published tag from [Mint releases](https://github.com/jamesonstone/mint/releases), rather than installing an unknown branch head. Mint's current build requires Go 1.25.5 or newer; check `go.mod` when upgrading.

```bash
go install github.com/jamesonstone/mint/cmd/mint@<published-tag>
mint version
mint help
```

Replace `<published-tag>` before running. An environment integration must pin a published immutable Mint commit containing schema 2 and team authorization support. Older releases may not support these features.

## Start with release-state publishing

For repositories that only need tags and GitHub Releases, this minimal workflow runs Mint's existing action. Replace `<published-mint-commit>` with the full commit SHA of a reviewed published release.

```yaml
name: Publish release state
on:
  push:
    branches: [main]
permissions:
  contents: write
concurrency:
  group: release-state
  cancel-in-progress: false
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
        with:
          fetch-depth: 0
      - uses: jamesonstone/mint@<published-mint-commit>
        with:
          command: release-publish
          commitish: ${{ github.sha }}
          owner: ${{ github.repository_owner }}
          repo: ${{ github.event.repository.name }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

This writes `.version` in the runner workspace without the leading `v`. It does not commit that file, build containers, or deploy. Add application-owned build steps explicitly. Use one release publisher; remove competing automatic version/tag publishers when adopting Mint.

For environment-controlled deployment, follow the next steps instead of publishing every source build as a canonical release.

## Add environment policy

Create `.mint.yaml` using the [sandbox policy example](https://jamesonstone.github.io/mint/environments.md#sandbox-first-policy). Set the real repository, trusted workflow paths and check names. Choose explicit `default_environment` when multiple environments exist.

For a team, use `authorization: repository-write`. Mint checks current effective GitHub write, maintain, or admin access for human requests, including team-derived access. Independent reviewers must also have write access. Bots and read/triage access cannot authorize releases. Optional `assignees` route work but grant no authority.

Legacy policies can retain `human_login`; do not combine it with `authorization`. Review a migration of authorization separately from a target-only release request.

## Release several components from one repository

A monorepo can promote each component through its own environments with its own
version line. Write one schema 2 policy file per component, each with a
`component` block. A `deployment` component also needs its own
`control_workflow`; `package` and `artifact` components run no controller:

```yaml
# .mint/backend.yaml
schema_version: 2
mode: deployment
repository: acme/app
default_branch: main
authorization: repository-write
build_workflow: .github/workflows/backend-build.yaml
control_workflow: .github/workflows/backend-mint.yaml
component:
  name: backend            # lowercase letters, digits, and -
  tag_prefix: backend/     # optional; defaults to <name>/
  paths: [backend]         # Git pathspecs this component owns
  changelog: backend/CHANGELOG.md
environments:
  production:
    scope: shared
    deploy: reviewed
    follow: latest
    promotion_workflow: .github/workflows/backend-deploy.yaml
    publish: true
```

A component policy keeps everything separate from other components and from a
repository-wide policy:

| Concern | Repository-wide | Component `backend` |
| --- | --- | --- |
| Versions | `vX.Y.Z` | `backend/vX.Y.Z`, only for commits touching `paths` |
| Journal | `mint-release-state[-<env>]` | `mint-release-state.backend.<env>` |
| Release-control files | `CHANGELOG.md`, `.mint/proposal.json`, `.mint/summary.md` | `changelog`, `.mint/backend/proposal.json`, `.mint/backend/summary.md` |
| Proposal marker | `<!-- mint:proposal:…` | `<!-- mint:component-proposal:backend:…` |
| Controller concurrency | `mint-release-journal` | `mint-release-journal-backend` |
| GitHub Release | marked Latest | never marked Latest |

Give each component its own build, deployment, and observation workflows, so
callback evidence stays unambiguous. Generate one controller per policy with
`--config .mint/backend.yaml` and `--output` set to that policy's
`control_workflow`. Pass the same file to the compatibility adapters with
`MINT_CONFIG=.mint/backend.yaml`, and to source versioning with
`version-config` (see [component releases](https://jamesonstone.github.io/mint/versioning.md#component-releases-in-one-repository)).
A target such as `target: backend/v1.4.0` must carry the component prefix.

## Connect trusted project adapters

| Adapter | Required evidence |
| --- | --- |
| Build producer | Successful trusted run with a single `mint-candidate.json` inside the `mint-candidate` Actions artifact. |
| Deployment | Upload `mint-request.json` as `mint-request` before start; deploy the frozen digests; upload exact verified `mint-deployment.json` as `mint-deployment` after verification. |
| Observation | Upload `mint-observation.json` as `mint-observation` with exact source/version, full artifact, runtime configuration, timestamp, run ID, and run URL. |

The deployment workflow receives `environment`, `intent_id`, and serialized `intent` inputs. It must consume these exact identities and avoid rebuilding. Mint validates server-side repository, default branch, workflow path, run identity/completion, archive digest, and manifest contents.

Use the [full adapter reference](https://github.com/jamesonstone/mint/blob/main/docs/references/environment-lifecycle.md#project-adapter-evidence) and [legacy integration contract](https://github.com/jamesonstone/mint/blob/main/docs/references/production-release-proposals.md) for manifest fields and controller wiring. These contracts are integration work: a policy file alone cannot make an existing deploy workflow compliant.

## Generate and review the controller

After the configured build, deploy, and observe workflow files exist, generate the repository controller:

```bash
mint deployment workflow \
  --config .mint.yaml \
  --environment sandbox \
  --mint-ref <published-mint-commit> \
  --output .github/workflows/mint-environments.yaml
```

The generator reads callback workflow names from the files, so create those adapters first. Review the generated default-branch controller and validation integration before merging. The controller needs contents/issues/pull-requests/Actions write and checks read; version/build jobs need contents write and Actions/pull-requests/checks read. Native CI can remain read-only. Use a job-scoped token; never embed credentials in policy or manifests. Configure repository rules to require exact-head checks and independent human review. GitHub must permit the controller token to create PRs when generated Release PRs are used.

## Activate a shared environment

1. Supply a real approved runtime `configuration_sha256` and trusted adapters.
2. Configure `baseline_workflow` (and `baseline_build_workflow` if migrating a different producer). Run the trusted baseline adapter to reconcile the actual running artifact/configuration and upload digest-attested `mint-baseline` evidence. Import it with `mint deployment bootstrap --environment sandbox --run-id <verified-run-id>`. Do not infer a baseline from an image tag, supply a local JSON file, or re-import to erase an uncertain deployment.
3. Review candidate production and retention, complete-bundle verification, required checks, and controller callback paths.
4. Enable `MINT_RELEASE_ENABLED` and the project's existing deployment gates only after those prerequisites are ready.
5. Promote an eligible candidate and inspect the Release PR and verified result end to end.

Generation, installation, or merging policy does not provision cloud resources, grant IAM, deploy a runtime, or activate an existing consumer.

## Check integration state

```bash
mint deployment policy --config .mint.yaml --environment sandbox
mint deployment status --config .mint.yaml --environment sandbox --format markdown
```

Policy inspection works before activation. Shared status reads authenticated repository state and needs the configured token (default `GH_TOKEN`). Treat missing evidence as unknown. Test a sandbox release and recovery before relying on the controller for a critical environment.


---

# Environments & sandboxes

Mint models environments by policy, not by a fixed development → staging → production ladder. A repository can contain only sandboxes, several shared test environments, local workspaces, or any project-owned combination.

## An arbitrary number of named environments

`environments` is a map with no fixed environment-count cap in the policy validator. Add entries as needed. Names must match `[a-z][a-z0-9_-]{0,62}`: a lowercase letter followed by up to 62 lowercase letters, digits, underscores, or hyphens.

This is configurable scale, not unlimited infrastructure. Each shared environment needs its own real runtime, approved configuration identity, verified baseline, adapter routing, retained artifacts, and GitHub Actions capacity. Mint does not provision or automatically delete ephemeral environments. Update policy and regenerate the controller when the environment list or callback workflows change.

## Sandbox-first policy

This onboarding example is valid policy but deliberately omits runtime configuration identities and baselines. Before deploying, set each shared environment's real `configuration_sha256` and establish trusted baseline evidence.

```yaml
schema_version: 2
mode: deployment
repository: owner/application
default_branch: main
default_environment: sandbox
authorization: repository-write
build_workflow: .github/workflows/build.yaml
validation_workflow: .github/workflows/checks.yaml
control_workflow: .github/workflows/mint-environments.yaml
required_checks: [Checks]
artifact:
  repository: ghcr.io/owner/application
environments:
  workspace:
    scope: local
    deploy: manual
    follow: latest
  sandbox:
    scope: shared
    deploy: automatic
    follow: latest
    image_tag: sandbox
    promotion_workflow: .github/workflows/deploy.yaml
    observation_workflow: .github/workflows/observe.yaml
  demo:
    scope: shared
    deploy: reviewed
    follow: latest
    requires: [sandbox]
    promotion_workflow: .github/workflows/deploy.yaml
    observation_workflow: .github/workflows/observe.yaml
  qa-pinned:
    scope: shared
    deploy: manual
    target: v1.2.3
    promotion_workflow: .github/workflows/deploy.yaml
    observation_workflow: .github/workflows/observe.yaml
```

Adapters shared by multiple entries must use the `environment` input to select the correct runtime and report that exact environment. The target `v1.2.3` must exist as authenticated eligible evidence before a request can deploy it. A full activated configuration adds, for example, `configuration_sha256: sha256:<64 lowercase hex digits>` using a genuine reviewed identity, not the placeholder.

## Choose scope and deployment policy

| Setting | Meaning |
| --- | --- |
| `scope: local` | Private machine observation cache; deployment remains your project's responsibility. |
| `scope: shared` | Authenticated repository journal and trusted adapters for a shared runtime. |
| `deploy: manual` | Collect candidates until an operator requests promotion. |
| `deploy: reviewed` | Keep one updating Release PR; checks and independent approval freeze its selection. |
| `deploy: automatic` | Follow previously approved policy without requiring a new Release PR for each ordinary candidate. |

Manual promotion enters the reviewed request path. Automatic mode still requires eligible trusted artifacts, activation, exact configuration, prerequisites, and verification. Use reviewed or manual mode for environments where a person must approve each change.

## Latest-following versus fixed targets

Choose exactly one of `follow: latest` or `target: vX.Y.Z`. Latest means the latest eligible candidate, not an arbitrary registry `latest` tag. A fixed target remains fixed until a reviewed policy change changes it.

`default_environment` determines the environment for omitted CLI selection and title-driven hotfixes. Without a default, omission works only for a single configured environment. Actions requests require an explicit environment.

`image_tag` is optional, must be unique across the policy, and must differ from immutable version tags. Aliases do not establish deployed state.

## Promote the same build

`requires: [sandbox]` makes `demo` depend on the sandbox having verified the complete selected artifact with no deployment in flight. Dependencies must name existing environments, contain no duplicates or cycles, and cannot make shared environments depend on local caches.

You can add `qa-east`, `qa-west`, or a reviewed `preview-42` as separate entries and reuse one candidate across them. Their runtime configurations and outcomes remain independent. A parallel dependency graph is valid; Mint does not force a single linear promotion chain.

## Publishing without production

No `production` entry is required. In deployment mode, optionally mark one shared environment `publish: true` to publish canonical releases after verification. At most one is allowed; naming it `distribution`, `demo`, or `live` does not change its evidence requirements.

For package/artifact projects, use `mode: package` or `mode: artifact` and keep the existing publication adapter. Those modes reject runtime operations and need no fabricated runtime state.


---

# Semantic versioning

Mint uses strict release tags in the form `vMAJOR.MINOR.PATCH`, such as `v2.4.1`. Prerelease and build-metadata tags are not strict release tags for Mint's resolver or selection commands.

## How the next version is chosen

The resolver evaluates commits since the highest reachable strict SemVer base tag. The strongest change wins.

| Commit signal | Bump | From `v1.2.3` |
| --- | --- | --- |
| Subject `!`, or body `BREAKING CHANGE:` / `BREAKING-CHANGE:` | Major | `v2.0.0` |
| `feat:` or `feat(scope):` | Minor | `v1.3.0` |
| `fix:`, `hotfix:`, other types, or non-conventional commits | Patch | `v1.2.4` |

Without a base, breaking changes start at `v1.0.0`, features at `v0.1.0`, and other changes at `v0.0.1`. Breaking changes increment major even for a `v0.x.y` base. There is no special pre-1.0 minor-bump exception.

For example, `feat(GH-42): :sparkles: add preview environments` triggers minor; `fix(api)!: remove legacy response fields` triggers major. A gitmoji in the description does not determine the bump.

## Resolve without publishing

```bash
mint release resolve --commitish HEAD
```

Resolution reads Git history; it does not push tags, publish images, or deploy. If the target already has strict SemVer tags, it reuses the highest and reports `already-tagged`.

Fetch full history and tags in CI. Shallow history cannot reliably establish the base or evaluated range.

## Component releases in one repository

A repository can release several components on independent version lines. Give
each component a tag prefix and the paths it owns:

```bash
mint release resolve --tag-prefix backend/ --path backend
mint release resolve --tag-prefix frontend/ --path frontend --path shared/ui
```

- Tags take the form `<prefix>vMAJOR.MINOR.PATCH`, for example `backend/v1.4.0`.
  A prefix contains letters, digits, `.`, `_`, `/`, or `-` and must be safe in a
  Git ref.
- Each scope only sees its own tags. Unprefixed resolution ignores `backend/…`
  tags, and a `backend/` scope ignores `v…` and `frontend/…` tags, so existing
  whole-repository releases keep working beside component releases.
- `--path` is a repeatable Git pathspec. Only commits that touch those paths
  count toward the bump, the commit count, and the release notes. A commit that
  touches two components counts for both.
- `select-tag`, `tag`, `github`, and `publish` accept `--tag-prefix` and reject
  tags outside the scope. `publish` also accepts `--path` and writes the bare
  `X.Y.Z` to the version file.
- In the GitHub Action, set `tag-prefix` and `paths` (one pathspec per line):

```yaml
- uses: jamesonstone/mint@v1
  with:
    command: release-publish
    tag-prefix: backend/
    paths: |
      backend
```

Without a prefix or paths, behavior is unchanged.

To source-version a component on every default-branch push, point
`version-main` at the component's schema 2 policy. Only first-parent commits
that touch the component's paths receive `<prefix>vX.Y.Z` tags, and the
policy's release-control files are treated as control-only:

```bash
mint release version-main --config .mint/backend.yaml --main-ref origin/main
```

In the Action, set `command: release-version-main` and
`version-config: .mint/backend.yaml`. For a component, the outputs describe the
target commit and add `component_changed`: `false` (with an empty
`version_tag`) when that commit did not touch the component's paths, so the
component's build job can skip instead of failing. Without `--config`, `version-main`
versions every commit on one unprefixed line, as before. See
[Integrate Mint](https://jamesonstone.github.io/mint/integration.md#release-several-components-from-one-repository)
for component environment policies.

## Source version versus deployed release

`mint release version-main` serially allocates one version for every untagged first-parent default-branch commit, oldest first. Controllers must use current authoritative main rather than an old triggering event SHA. Occupied tags, including isolated hotfix tags, are skipped by advancing patch until a free version is found.

Trusted release-control-only commits also receive a source identity, but do not become application build candidates or add noise to application release notes. Source versioning does not create a GitHub Release or prove artifact eligibility. A selected environment release may include several source versions since its last verified deployment.

## Immutable tags

`mint release tag` creates or reuses an annotated tag at an exact source commit. A tag already pointing at that commit is reusable; one pointing elsewhere is a conflict. Mint never moves a conflicting tag.

Inspect the conflicting tag and source identities before retrying. Do not repoint a published version to repair a deployment. Correct or revert source and release a new version, or request a retained-artifact rollback.

## Select an existing version

```bash
mint release select-tag --commitish HEAD
```

Without `--requested-tag`, Mint selects the highest strict SemVer tag on the exact target commit and fails if none exists. With `--requested-tag v1.2.3`, it validates the version syntax and returns that selection; this alone does not prove the requested artifact exists, matches the commit, or was deployed. Environment requests additionally require authenticated candidate/history evidence.

## Hotfix version series

An isolated hotfix allocates the next unused patch in the verified deployed version's series. If that environment is on `v1.2.3` while ordinary work has reached `v1.3.0`, the fix remains in `v1.2.x`; occupied patches are skipped. Merge the correction back into ordinary source so later releases keep it.


---

# CHANGELOG integration

Mint generates linked Markdown release notes from Git commit history. Good Conventional Commit subjects make both version decisions and changelog entries understandable.

## Generate a release entry

```bash
mint changelog \
  --prev-tag v1.2.3 \
  --current-tag v1.3.0 \
  --owner owner \
  --repo application \
  --output CHANGELOG.md
```

For the first entry, omit `--prev-tag`. When the new version tag does not exist yet, identify the actual range end with `--current-ref`:

```bash
mint changelog \
  --prev-tag v1.2.3 \
  --current-tag v1.3.0 \
  --current-ref HEAD \
  --owner owner \
  --repo application
```

The heading uses the current version and links to its GitHub Release. The date comes from the range-end commit's author date. Entries link to commits. Issue links come from a commit-body closing reference such as `Closes #42`, or a trailing `(#42)` in the subject. A scope such as `GH-42` appears as a scope label; it does not itself create an issue link.

## Which commits appear

| Group | Included changes |
| --- | --- |
| breaking changes | Included commit types marked with `!` or a `BREAKING CHANGE:` body. |
| features | Non-breaking `feat`. |
| fixes | Non-breaking `fix` and `hotfix`. |
| perf | Non-breaking `perf`. |
| other | Non-breaking `refactor`, `build`, and `ci`. |

The changelog parser requires a valid Conventional Commit header and warns about unrecognized entries. `docs`, `test`, and `chore` are excluded even if marked breaking; `style` is not a recognized changelog type. The changelog parser recognizes the space form `BREAKING CHANGE:`; the version resolver also recognizes `BREAKING-CHANGE:`. Do not confuse changelog inclusion with version impact: the version resolver still treats other and non-conventional changes as patch changes.

## Per-component changelogs

For a component released with a tag prefix, write its own changelog and limit
entries to its paths:

```bash
mint --prev-tag backend/v1.3.0 --current-tag backend/v1.4.0 --current-ref HEAD \
  --owner acme --repo app --output backend/CHANGELOG.md \
  --tag-prefix backend/ --path backend
```

The header keeps the bare version and links to the prefixed tag:

```text
## [1.4.0](https://github.com/acme/app/releases/tag/backend/v1.4.0) - 2026-10-13
```

Mint rejects a current or previous tag that does not start with the prefix.
In the GitHub Action, use the `tag-prefix` and `paths` inputs with
`command: changelog`.

## Existing changelogs and retries

The command prepends a release block while preserving older entries and file permissions. Existing `##` headings must use Mint's parseable release-heading format. It rejects duplicate versions, malformed release headings, missing range refs, and empty ranges rather than silently overwriting history.

A duplicate-version retry is an error, not an idempotent append. Inspect the existing entry before running again. For compatibility, the root CLI also accepts the changelog flags directly.

## Connect CHANGELOG to the Release PR

In reviewed environment releases, `CHANGELOG.md` is a release-control path alongside `.mint/proposal.json` and `.mint/summary.md`. The controller maintains release metadata while eligible candidates advance. Review the proposed version, included changes, source, complete artifact, and runtime configuration on the current PR head.

Control-only commits are classified separately from application work, avoiding a release loop caused by the generated changelog itself. Keep the configured control paths exact; do not expand them to arbitrary source files.

The standalone changelog command writes a local file; it does not open a PR, publish a GitHub Release, or deploy. `release publish` writes its own resolved release notes and does not automatically commit your CHANGELOG. Choose one owner for changelog updates so competing workflows do not duplicate entries.


---

# Release PRs

A Release PR is the review surface for an exact artifact selection and runtime configuration. It is distinct from a source PR: it approves deployment of an already built candidate.

## One updating PR per reviewed environment

As successful eligible builds arrive, the normal Release PR updates to follow the environment's policy. Its declaration and summary are machine-owned release metadata. Independent human approval and required checks must match the exact current head.

Before approval, the selection can change. Approval freezes the complete selected artifact and configuration; later candidates cannot silently replace that frozen intent. Mint retains queued work for a later release.

## Review checklist

- Correct environment and operation: ordinary release, rollback, or hotfix.
- Exact source/version and complete immutable artifact digest or bundle.
- Approved runtime configuration identity and satisfied prerequisites.
- CHANGELOG and summary cover the intended changes.
- Required checks and independent approval apply to this exact head.

For `authorization: repository-write`, requests and independent human reviews require current effective write, maintain, or admin permission. Assignment alone grants no authority. Legacy named-operator policies retain their existing authorization model.

## Target-only policy requests

A PR can change one environment's `target`, `follow`, `operation`, or `reason` and act as its own deployment approval. Requests need an exact target except for `operation: resume`.

```yaml
target: v1.2.3
operation: rollback
reason: Restore the last verified authentication artifact
```

Replace `follow: latest` rather than keeping both. The target must exist in authenticated candidate or verified history as appropriate.

Mint compares policy before the first PR commit and before merge. A target request cannot weaken checks, change adapters, configuration, authorization, publisher, or prerequisites and then approve itself. Review those authority changes separately. Mint creates no second approval PR or separate status PR for a target-only request.

## After merge

The controller verifies approval, freezes intent, and dispatches the project adapter. The adapter reports start and verifies the exact environment/artifact/configuration tuple. Only matching trusted successful evidence advances deployment history.

Mint reports the result on the original approval PR using an idempotent machine-owned comment; human comments are preserved. Canonical publication is a separate retryable outcome after verification. A failed publication can be retried without redeploying the artifact.

A merged PR or accepted workflow dispatch is not proof of deployment. If evidence is incomplete or contradictory, the environment remains fenced until [reconciliation](https://jamesonstone.github.io/mint/recovery.md#reconcile-an-uncertain-deployment).

## Manual and automatic environments

Manual environments wait for an operator's **promote** request and then use the reviewed request path. Automatic environments deploy eligible candidates under previously approved policy; ordinary releases do not require a new review PR. Both still require trusted artifacts, exact configuration and verification.


---

# Rollback & hotfix

Prefer roll-forward when practical: correct or revert source, build it, and release a new version. Use rollback for retained-artifact recovery and hotfix to isolate a correction from queued default-branch work.

## Request recovery in Actions

Open **Actions → Mint environment control → Run workflow**. Select the environment explicitly and choose an operation.

| Operation | Input and result |
| --- | --- |
| `promote` | Optionally choose an eligible exact version and request reviewed promotion. |
| `hotfix` | Supply a fix PR or issue and a reason; prepare an isolated correction against verified deployment. |
| `rollback` | Supply a reason and optionally a retained verified version; otherwise select the previous distinct verified artifact. |
| `resume` | Make a fresh request to clear the pause caused by rollback. |
| `observe` | Request fresh read-only runtime evidence from the trusted observer. |
| `reconcile` | Supply the active intent, or leave it blank for the current fence, and a fresh successful observer run. |

These are repository controller requests. They require an activated integration and authenticated human authority; a local command invocation alone is not permission to deploy.

## Roll back a retained artifact

1. Inspect verified history and confirm the artifact or complete bundle is still retained and available.
2. Request **rollback** with a reason and, optionally, an exact previously verified version.
3. Review the recovery PR's artifact and current runtime configuration; merge after current-head checks and independent approval.
4. Inspect matching adapter verification and the outcome on the same PR.
5. When ready for ordinary releases, make a fresh **resume** request.

Rollback uses **current trusted runtime configuration**, not historical configuration. It does not reverse database migrations, data changes, or external side effects. To recover configuration, review the desired configuration and deploy it explicitly.

After a successful rollback, latest-following releases pause to avoid immediately redeploying the version just rolled back. Replaying an old resume request cannot clear a later pause. A fixed policy target stays fixed after resume.

## Isolate a hotfix

Use an Actions **hotfix** request with a merged reviewed fix PR, or an issue for authoring a new isolated correction. A source PR titled `hotfix: ...`, `hotfix(component): ...`, or `hotfix(GH-123): :firetruck: ...` can also initiate the trusted hotfix path after source review and merge.

With multiple environments, configure `default_environment` for title-driven requests. Mint prepares isolated source against that environment's verified deployment rather than pulling in unrelated queued changes. Review the source correction and then the release selection; the hotfix still needs build and deployment verification.

The version is the next unused patch in the deployed compatibility series. Integrate the correction into the default branch so future ordinary releases retain it.

The hotfix source PR is bound to the verified baseline it was prepared from. If another release deploys before the source PR merges, Mint rejects the stale hotfix instead of attributing it to the new baseline; request the hotfix again against the current deployment.

For a [component policy](https://jamesonstone.github.io/mint/integration.md#release-several-components-from-one-repository), the production base is `mint-hotfix-base/<component>/GH-<issue>`, the source PR carries `<!-- mint:component-hotfix-source:<component>:…`, and the version keeps the component prefix (`backend/v1.4.1`). Use one component per hotfix issue: request a separate issue for each component that needs a correction.

## Reconcile an uncertain deployment

Missing, mixed, or conflicting deployment evidence leaves a fence in place. A successful dispatch or standalone observation does not clear it.

1. Establish that the original adapter run has completed.
2. Request **observe** and obtain a trusted successful observation taken after that completion.
3. Request **reconcile** using that observer run and the active intent.
4. Mint compares the full observed identity with the frozen selection and previous verified baseline.

An exact match to the frozen selection establishes success. An exact match to the previous baseline establishes a failed deployment with unchanged runtime. Any other state retains the fence for investigation. All bundle members and configuration identity must match.

Successful reconciliation also retries pending publication. Replaying reconciliation may retry publication without redeployment. Reviewed and automatic unpaused environments restore a reviewed PR for queued work after explicit recovery; manual environments still need promotion.

## Read status without overclaiming

```bash
mint deployment status --environment sandbox --format markdown
```

Read desired policy, last verified deployment, and live observation separately. `live`, `drift`, `deploying`, and `unknown` describe authenticated evidence; an observation timestamp limits what it proves. Do not substitute an old verified version for a fresh runtime observation.