ATR release runbook (Apache Trusted Releases)

The Apache Trusted Releases (ATR) backend for an Apache release: compose a signed release candidate in the ATR web platform, let ATR run the policy checks and drive the [VOTE], then finish the release so it is published to dist.apache.org and announced.

This runbook is the ATR counterpart of the svn-release-runbook.md. Both describe the same 14-step lifecycle and are driven by the same release-management skills — they differ only in the distribution / approval / announce backend the mechanical middle runs against:

	`svnpubsub` runbook	ATR runbook (this doc)
Stage RC	`svn import` to `dist/dev/<rc>/`	Compose phase: upload to ATR
Run checks	RM/voters run `release-verify-rc` locally	Compose checks run automatically in ATR + local verify
Vote	RM sends `[VOTE]`, tallies by hand	Vote phase: ATR sends `[VOTE]`, tabulates
Promote	`svn mv dist/dev → dist/release`	Finish phase: ATR strips `-rcN`, publishes
Announce	RM sends `[ANNOUNCE]`	Finish phase: ATR-assisted announce

atr is a value of the release_dist_backend switch, alongside svnpubsub. The 14 abstract steps are identical; only the commands the RM (and the skills) emit change.

Why ATR

The traditional svnpubsub flow scatters a release across a signed tag, a hand-built .zip, a detached signature, a checksum, an svn import to dist/dev/, a manually-composed [VOTE] email, a manual tally, and an svn mv to dist/release/. Every one of those is a place to get the mechanics wrong (bad signature, md5 instead of sha512, a stray file in the .zip, staging to the wrong bucket).

ATR moves the mechanical middle onto a platform that:

Runs the policy checks for you, on upload. Signature, checksum, LICENSE, NOTICE, and source-header checks fire asynchronously the moment a candidate is composed, so the RM gets fast feedback on policy compliance before asking anyone to vote.
Automates the vote. ATR sends the [VOTE] email to dev@ and tabulates the replies over the 72-hour window.
Publishes atomically on finish. Finishing strips the -rcN tags from filenames, rearranges the directory structure, and publishes to dist.apache.org — replacing the error-prone svn mv promotion.

This keeps the release policy-compliant by construction, which is the point of ATR: releases that are trusted because the platform, not a tired human at 2am, enforced the mechanics.

Status: beta

Important

ATR is an ASF Tooling platform, now in beta. The platform runs at https://releases.apache.org/; the older release-test.apache.org now redirects there. A static release catalogue is served separately at https://release-catalog.apache.org/.

The atr client and API schema are still not stable — beta is not a stability guarantee, so do not pin unattended scripts to them. The client repository carries no tags and no releases and is installed straight from main, so there is no version to pin to even if you wanted one. Exact client subcommand names may shift; where this runbook gives a command, treat it as the shape of the operation and confirm the current verb with atr --help and the ATR user guide.

Until Magpie’s PMC ratifies ATR as the project’s release backend, the svnpubsub runbook remains the canonical path and this document is the forward-looking target. Coordinate on dev@tooling.apache.org / #apache-trusted-releases on ASF Slack before cutting a real release through ATR.

Important

Magpie runs the full ATR flow. There is no hybrid mode. Both config keys in release-management-config.md are atr: release_dist_backend = atr and release_vote_backend = atr. Every row of the table below applies — Compose, Vote and Finish.

Compose — the signed artefacts are staged in ATR, and only there. Nothing is written to SVN dist/dev.
Vote — ATR sends the [VOTE] to dev@ and tabulates it. The default template links the ATR candidate page and the committee KEYS file, which is what voters download from.
Finish — ATR commits the approved artefacts to dist/release. No manual svn mv.

This supersedes the earlier hybrid (release_dist_backend = svnpubsub with release_vote_backend = atr), under which artefacts lived in two places and the [VOTE] pointed at the SVN copy while the checks ran against the ATR one. That shape is retired; see #1182 for the discussion that settled it, and manual-release-process.md for what the 0.1.0 release actually did under it.

One staging location is the point, not a detail. ATR’s default vote template “deliberately does not link to any other source of the same artifacts”, because with two copies in play “voters may then be voting on different bytes to one another” (Staging and voting). Under the full flow the bytes voted on are the bytes Finish commits, with the checksum recorded alongside and no human step between — which is precisely the provenance property the hybrid could not offer.

Finish does not make ATR the host. It commits into the same Apache distribution SVN repository the svnpubsub flow promotes into, and “No manual SVN step is needed to publish a release” (Promoting to release). What changes is whether the RM runs svn mv or ATR commits on the project’s behalf.

Resolving this is a PMC decision, tracked in #1182. The policy is unchanged until that resolves.

The three ATR phases vs the 14-step lifecycle

ATR organises a release into three phases. They map onto the 14-step lifecycle — and onto the release skills that own each step — like this:

ATR phase	Lifecycle steps	Owning skill(s)	What happens
(pre-phase)	1 Plan · 2 Changelog/NOTICE/LICENSE	`release-prepare`	Planning issue + version-bump PR. Off-platform; unchanged.
(pre-phase)	3 `KEYS`	`release-keys-sync`	RM’s public key added to the committee’s `KEYS` in ATR.
Compose	4 Cut RC · 5 Stage · 6 Verify	`release-rc-cut`, `release-verify-rc`	Build the source artefact, sign it, upload it to ATR as a draft; ATR runs signature/checksum/license/notice/source-header checks automatically.
Vote	7 `[VOTE]` · 8 Window · 9 Tally	`release-vote-draft`, `release-vote-tally`	ATR sends the `[VOTE]` to `dev@` and tabulates replies over ≥72h. The skills draft the body and cross-check the tally against the PMC roster.
Finish	10 Promote · 11 Announce	`release-promote`, `release-announce-draft`	ATR strips `-rcN`, rearranges the tree, publishes to `dist.apache.org`, and assists the `[ANNOUNCE]`. Records downstream distributions (PyPI, Maven Central).
(post-phase)	12 Archive · 13 Audit · 14 Post-bump	`release-archive-sweep`, `release-audit-report`, `release-prepare`	Archiving in ATR, audit-log record, `-SNAPSHOT`/`.dev` bump.

The takeaway: ATR replaces the mechanics of Steps 5–12, including archiving. Steps 1–4 (plan, changelog, keys, build) and 13–14 (audit, post-bump) are the same regardless of backend, and the same skills drive them.

What ATR does not change

The source package is still the release. ATR votes on the source artefact; binaries/wheels remain convenience (release-policy § what is a release).
The vote is still a dev@ list vote with a ≥72h window, ≥3 binding +1, and more +1 than -1 (release-policy § release approval). ATR drives it; it does not replace the PMC’s binding vote.
The RM still signs. ATR verifies signatures; it never holds the RM’s private key. Signing happens on the RM’s machine (or a hardware key), exactly as with svnpubsub.
announce@apache.org is still mandatory for the TLP announcement (release-policy § announcements).

State-change boundaries (unchanged from `svnpubsub`)

The two non-negotiable spec boundaries hold identically on the ATR backend — ATR changes where artefacts live, not who acts:

The agent never holds, invokes, or proxies the RM’s signing key. The build-and-sign of the artefact (Step 4) runs on the RM’s machine; the agent emits the recipe, the RM runs it and signs. (spec § Boundary 1).
The agent never publishes the release. Composing a draft and starting a vote are RM actions in ATR; finishing (publishing) is the moment of release and is an RM/PMC action in the ATR UI or via the authenticated client. The skills draft; the human confirms and clicks/commits. (spec § Boundary 2).

Concretely: the release skills that emit paste-ready commands (release-rc-cut, release-promote) now emit ATR client commands instead of svn commands, but they still emit — they do not run the publishing step themselves.

Prerequisites

Before you start, confirm:

You are a committer on the Magpie committee and can authenticate to ATR with your ASF credentials.
Your OpenPGP key is registered in ATR for the Magpie committee (the ATR equivalent of being in the KEYS file — see Step B). If this is your first release, run release-keys-sync (Step 3) first.
The prep PR is merged — version strings, CHANGELOG, NOTICE/LICENSE reflect <version> (release-prepare, Step 2).
git, gpg, and Python 3.12+ are installed locally (the atr client needs 3.12+).

One-time setup: the `atr` client

The atr client lets you drive a release from the machine where the artefacts were built. Install it once:

# Option 1 — uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "apache-trusted-releases @ git+https://github.com/apache/tooling-releases-client"

# Option 2 — pip in a venv
python3 -m venv venv && source venv/bin/activate
pip3 install -U pip setuptools wheel
pip3 install "git+https://github.com/apache/tooling-releases-client"

atr --version

Authenticate against the ATR deployment (get the PAT from your profile page in the ATR web UI):

atr set asf.uid <your-asf-id>
atr set tokens.pat "<personal-access-token-from-atr-site>"
atr jwt refresh          # exchanges the PAT for a short-lived JWT

Step A: Prep + version bump (unchanged)

Identical to the svnpubsub flow. Run release-prepare:

It opens the release-planning issue (Step 1).
It drafts the version-bump + CHANGELOG + NOTICE/LICENSE PR (Step 2). Merge it before composing the RC.

No ATR interaction yet — this is ordinary repo work.

Step B: `KEYS` in ATR (Step 3)

On svnpubsub, your public key must appear in dist/release/magpie/KEYS. On ATR, the committee’s keys live in the platform: ATR stores the KEYS set and validates candidate signatures against it during Compose.

If this is your first Magpie release, run release-keys-sync to produce the public-key block, then register it:

# Register your public key with the Magpie committee in ATR
# (web UI: Committee → Keys → Add key; or the client/API equivalent
#  of POST /api/key/add — confirm the exact verb with `atr --help`)
gpg --armor --export <your-key-fingerprint> > my-public-key.asc
# upload my-public-key.asc via the ATR UI or client

The agent drafts the key block and the diff; you own the private key and perform the registration (spec § Boundary 1).

Step C: Compose the release candidate (Steps 4-6)

Compose is the ATR replacement for svn import + local verify.

Build and sign the source artefact locally — this half is unchanged from the svnpubsub runbook Steps 2–5. release-rc-cut emits the recipe from release-build.md:

export VERSION=0.1.0
export RC=rc1
export RC_TAG="${VERSION}-${RC}"
export ARTIFACT="apache-magpie-${VERSION}-source.zip"

git tag -s "${RC_TAG}" -m "Apache Magpie ${VERSION} ${RC}" HEAD
git push origin "${RC_TAG}"

git archive --format=zip \
  --prefix="apache-magpie-${VERSION}/" \
  -o "${ARTIFACT}" "${RC_TAG}"

gpg --armor --detach-sign "${ARTIFACT}"      # -> ${ARTIFACT}.asc
sha512sum "${ARTIFACT}" > "${ARTIFACT}.sha512"

The build and the signature happen on your machine, with your key. ATR receives an already-signed artefact; it never signs for you.

Create the draft release and upload to ATR (Compose):

# Start a draft release for magpie <version>, then upload the artefact
# + signature + checksum. ATR tracks *revisions*, not rc-numbers: each
# upload adds to the current revision (the rcN identity lives in the tag
# and the [VOTE] subject, not in the ATR release name). `atr upload` takes
# PROJECT VERSION PATH FILEPATH — PATH is the file's name inside the
# release, FILEPATH the local file — so upload one file per call.
# (Verbs per the client's COMMANDS.md; run `atr <cmd> --help` for flags.)
atr release start magpie "${VERSION}"
atr upload magpie "${VERSION}" "${ARTIFACT}"        "${ARTIFACT}"
atr upload magpie "${VERSION}" "${ARTIFACT}.asc"    "${ARTIFACT}.asc"
atr upload magpie "${VERSION}" "${ARTIFACT}.sha512" "${ARTIFACT}.sha512"

Let the checks run. On upload, ATR fires asynchronous checks: signature (against the committee KEYS), checksum, license, notice, and source-header (RAT-style) checks. Poll them:
```
atr revisions magpie "${VERSION}"                # list revisions; note the revision id
atr check status magpie "${VERSION}" --verbose   # poll checks
# review a specific revision's hard blockers and non-blocking concerns:
#   atr check blockers magpie "${VERSION}" <revision>
#   atr check concerns magpie "${VERSION}" <revision>
```
Fix any failing check and re-upload a new revision before voting. This is the platform-run equivalent of release-verify-rc; you can still run release-verify-rc locally for a second, independent read (voters can too, in their own dev loop).

Step D: Vote (Steps 7-9)

ATR automates the mechanics of the dev@ vote; the PMC still casts the binding votes.

Draft the [VOTE] body with release-vote-draft. It produces the subject ([VOTE] Release Apache Magpie <version> from <version>-rcN) and body — pointing voters at the ATR candidate page and its check results, and carrying the How to verify this candidate section every Magpie [VOTE] has: the reproducibility record (source commit, SOURCE_DATE_EPOCH, sha512 from the planning issue), the agentic one-liner (/magpie-release-management:verify-rc <version>-rcN), the human-readable page (manual-release-process.md § Manual verification at the RC tag), the reproducibility background, and the voter-obligation sentence. ATR’s default vote text links only the candidate page, so the drafted body is what the RM supplies to ATR (the client’s body option or the vote form on the candidate page; confirm with atr vote start --help) — do not let the default stand.

Start the vote in ATR. The RM triggers the vote for the composed candidate; ATR sends the [VOTE] email to dev@magpie.apache.org and opens the tabulation. Starting the vote is an RM action — the agent drafts, the RM starts:

# atr vote start PROJECT VERSION REVISION -m LIST [--duration H] [--subject S] [CONCERNS-NOTED]
# REVISION comes from `atr revisions magpie "${VERSION}"` (or the candidate page).
# If `atr check concerns` flagged non-blocking concerns, start the vote WITH the
# concerns-noted flag so they're acknowledged in the thread (see `atr vote start --help`).
atr vote start magpie "${VERSION}" <revision> \
  -m dev@magpie.apache.org --duration "${VOTE_WINDOW_HOURS:-72}" \
  --subject "[VOTE] Release Apache Magpie ${VERSION} from ${RC_TAG}"

72-hour window (Step 8). Minimum per release-policy § release approval; the Magpie config may lengthen but not shorten it (release-management-config.md § Vote). What a PMC member does during the window, in either order:
- Agentic: /magpie-release-management:verify-rc <version>-rcN from any Magpie-enabled agent — read-only; it fetches the staged artefacts, checks signature / checksum / RAT / LICENSE-NOTICE / binaries / links / version strings, rebuilds the source archive from the tag and reports identical, content-identical or differs.
- Manual: the linked verification page at the RC tag — the same checks longhand, ending with a build and test run from the unpacked source.
- Reply on the thread using the reply template: the commit you verified, the compare verdict, and what you built and tested on. A binding +1 is the voter’s own statement, not the tool’s.
Tally (Step 9). ATR tabulates the replies; cross-check with release-vote-tally, which classifies each reply binding-vs-non-binding against the pmc-roster.md and drafts the [RESULT] [VOTE]. On any ambiguity the skill refuses to count and flags AMBIGUOUS, needs RM call — the binding tally is the PMC’s, not the platform’s. If the vote fails, bump RC and return to Step C.

Step E: Finish + announce (Steps 10-11)

Finish is the ATR replacement for the svn mv dist/dev → dist/release promotion and the [ANNOUNCE]. This is the moment of release.

Finish the release in ATR once the vote has passed. Finishing:
- strips the -rcN tag from artefact filenames,
- rearranges the directory structure into the release layout,
- publishes the artefacts to dist.apache.org (the release area) via ATR.
release-promote now emits the Finish command (the client/API equivalent of the promote) instead of the svn mv. Finishing is an RM/PMC action — the agent drafts the command; the human runs it (spec § Boundary 2).
```
# Publish the voted candidate as the release. Confirm the exact
# verb with `atr --help`.
atr release finish magpie "${VERSION}"
```
Announce (Step 11). release-announce-draft drafts the [ANNOUNCE] body (subject [ANNOUNCE] Apache Magpie <version> released) for announce@apache.org, cc dev@ — mandatory per release-policy § announcements — and the site-bump PR against site-repo.md. ATR can assist the announce; the agent never sends the mail and never merges the site PR.
Record downstream distributions. If Magpie ships convenience artefacts (e.g. a PyPI package), record each downstream location in ATR (POST /api/distribution/record) so the release catalog and audit trail are complete.

Step F: Archive, audit, post-release bump (Steps 12-14)

Archive sweep (Step 12): follow the retention rule in release-management-config.md § Archive. Releases committed to dist/release are copied to archive.apache.org automatically. Archiving a release in ATR updates the release catalog and removes its files from dist/release in the background. If enabled in the project settings, select “Auto archive prior release” to archive the previous release in the same cycle when announcing the new release. See Promoting to release.
Audit log (Step 13) — release-audit-report appends the per-release record (RM, binding voters, artefacts + sigs + checksums, the ATR candidate/finish references, [ANNOUNCE] archive URL) to the audit log.
Post-release version bump (Step 14) — release-prepare drafts the -SNAPSHOT/.dev bump PR so main is open for the next line.

GitHub Actions path (reproducible builds)

For a project with a reproducible build, ATR can compose a candidate directly from CI using apache/tooling-actions, authenticating to ATR with GitHub OIDC (no long-lived token in the repo). The workflow builds the artefact, uploads it to ATR, and triggers the checks — the same Compose phase, driven from Actions instead of the RM’s laptop.

This does not move the signing key into CI unless the project has adopted a reproducible-build + trusted-publishing model the PMC has explicitly signed off on. For Magpie’s first releases, prefer the local atr client path above (Step C); revisit CI-driven compose once the build is demonstrably reproducible. When it is, release-prepare automated-signing drafts the Infra key request, the Security Team notification and the workflow PR (template: projects/_template/workflows/release-candidate.yml) under the conditions in Infra § Automated release signing; see reproducibility.md. See the tooling-asf-example repository for a worked GitHub Actions example.

Release Manager checklist

Cross-references

process.md — the 14-step lifecycle this runbook drives against the ATR backend.
svn-release-runbook.md — the svnpubsub counterpart; same lifecycle, different backend.
spec.md — the state-change boundaries (agent never holds the key, never publishes) that hold identically on ATR.
README.md — the release-management skill family that drives every step.
release-management-config.md — where the atr distribution backend is selected.
ATR platform — beta deployment · release catalogue · user docs · API docs · platform source · atr client · GitHub Actions · worked example. Discussion: dev@tooling.apache.org / #apache-trusted-releases on ASF Slack.
ASF release policy, release distribution, release signing — the canonical foundation references ATR enforces.