docs: document the release and install pipeline by norrietaylor · Pull Request #867 · gominimal/minimal

norrietaylor · 2026-07-21T19:01:12Z

Adds docs/internal/release-pipeline.md — the maintainer-facing release/install pipeline runbook. Originally part of #858; pulled out to land on its own.

What

A single internal doc covering release.yml, the stable/unstable/nightly channels, staging, promotion (approval gate + nightly-provenance check + override_provenance), pruning, and the operator runbook. Marked internal (publicly visible in the repo, not published to a docs site).

Verification

All relative links resolve on main (scripts/*.sh, .github/workflows/*.yml, docs/ci-strategy.md).
Scrub clean: no emails, no secret-shaped tokens, and no private-repo names. The reference-docs-promoted promotion dispatch is described abstractly (it rebuilds docs.minimal.dev) rather than naming the private docs-site repo.

Note

The docs/internal/README.md index row for this doc lives in #858; once both land, that index should regain a release-pipeline.md row.

🤖 Generated with Claude Code

Note

Document the release pipeline and strengthen nightly provenance verification

Adds release-pipeline.md documenting the bucket-centric release pipeline, covering release.yml, nightly.yml, promote.yml, prune-releases.yml, the curl|sh installer behavior, and an operational runbook.
Strengthens verify-nightly-provenance.sh to require that the matching nightly run includes a smoke-success aggregator job with conclusion success, plus both smoke-linux-amd64 and smoke-linux-kvm jobs concluded success; no-op runs where smokes were skipped are now rejected.
Extends verify-nightly-provenance_test.sh with test cases covering skipped smokes, no-op nightly runs, macOS-only skips, and failure/cancelled aggregator states.
Behavioral Change: the provenance script now fails for previously-accepted nightly runs where Linux smoke jobs were skipped.

^{Macroscope summarized 729a12f.}

Add docs/internal/release-pipeline.md, a maintainer-facing runbook for the release/install pipeline: release.yml, the stable/unstable/nightly channels, staging, promotion, pruning, and the operator steps. Marked internal (publicly visible in the repo, not published to the docs site). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-07-21T19:01:20Z

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6ea034ad-b18c-4d39-a1ce-c85e9d0459c5

📥 Commits

Reviewing files that changed from the base of the PR and between 4bfdcb0 and 729a12f.

📒 Files selected for processing (3)

docs/internal/release-pipeline.md
scripts/verify-nightly-provenance.sh
scripts/verify-nightly-provenance_test.sh

_{Comment @coderabbitai help to get the list of available commands.}

…in release-pipeline.md (#900) Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

The reference-docs promotion dispatch named the docs-site repo and its GitHub App. That repo is private, so this public repo should not announce it, and the promote pipeline is being reshaped besides. Describe the `reference-docs-promoted` dispatch abstractly (it triggers a docs.minimal.dev rebuild) without naming the target repo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

macroscopeapp · 2026-07-22T15:30:31Z

+workflow's approver allowlist (the initiating user is excluded) comments
+`approved` / `denied`; closing the issue without approval counts as denial.
+
+**nightly-provenance gate.** Before flipping the pointer, the `promote` job


🟡 Medium internal/release-pipeline.md:105

The nightly-provenance gate does not actually guarantee that a version completed the smoke suite. verify-nightly-provenance.sh accepts any successful nightly.yml run at the SHA, including a no-op run where the check job found an already-staged version and all release/smoke jobs were skipped — so a manually dispatched or tag-staged version can later pass this gate without ever running smoke tests. This contradicts the claim on lines 108–112 that such builds are rejected and stable only receives fully smoked versions. Either tighten the provenance check to require the smoke jobs to have actually run (not just the workflow to have succeeded), or correct the documentation to state that the gate only confirms nightly.yml reported success, not that smoke tests executed.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @docs/internal/release-pipeline.md around line 105: The nightly-provenance gate does not actually guarantee that a version completed the smoke suite. `verify-nightly-provenance.sh` accepts any successful `nightly.yml` run at the SHA, including a no-op run where the `check` job found an already-staged version and all release/smoke jobs were skipped — so a manually dispatched or tag-staged version can later pass this gate without ever running smoke tests. This contradicts the claim on lines 108–112 that such builds are rejected and stable only receives fully smoked versions. Either tighten the provenance check to require the smoke jobs to have actually run (not just the workflow to have succeeded), or correct the documentation to state that the gate only confirms `nightly.yml` reported success, not that smoke tests executed.

fix it for me

we should tighten the provenance

I'm working on tightening the provenance check. The fix will modify verify-nightly-provenance.sh to verify that the smoke-success job actually ran and succeeded (not just that the workflow completed), ensuring only fully smoke-tested versions can be promoted to stable.

Added smoke-success job verification to scripts/verify-nightly-provenance.sh. After finding a matching nightly run, the script now queries the jobs endpoint and verifies the smoke-success aggregator job has conclusion == "success" (not "skipped"), ensuring promoted versions actually completed the smoke test suite. Updated tests cover skipped, missing, failed, and cancelled smoke-success scenarios.
Commit 4c8a03f pushed to #911. When checks pass, it will merge automatically into this PR.

I automatically merged #911 into this PR (934546a).

…heck (#911) Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

…se runbook

smoke-success is if: always() and skip-tolerant, so a no-op nightly run (SHA already staged, smokes skipped) still concluded success and could vouch for a version that was never smoked. The gate now also requires the Linux smoke jobs themselves to have run and passed; smoke-macos alone may be skipped by the RUN_MACOS_CI kill-switch. Test fixtures move to name/conclusion pairs and cover the real no-op shape and the kill-switch shape (31 tests). The runbook text now states the guarantee precisely, drops the unsourced retirement claim, and documents the channel-endpoint target override. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

macroscopeapp Bot reviewed Jul 21, 2026

View reviewed changes

Comment thread docs/internal/release-pipeline.md Outdated

Comment thread docs/internal/release-pipeline.md

norrietaylor mentioned this pull request Jul 21, 2026

docs: rework README and add AGENTS.md and the docs landing page #871

Merged

macroscopeapp Bot mentioned this pull request Jul 22, 2026

(via norrietaylor): docs: document nightly-provenance gate and override_provenance input in #900

Merged

macroscopeapp Bot and others added 2 commits July 22, 2026 04:58

docs: document nightly-provenance gate and override_provenance input …

4e9bc96

…in release-pipeline.md (#900) Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

macroscopeapp Bot reviewed Jul 22, 2026

View reviewed changes

macroscopeapp Bot mentioned this pull request Jul 22, 2026

(via norrietaylor): fix(release): verify smoke tests actually ran in nightly provenance chec #911

Merged

macroscopeapp Bot and others added 2 commits July 22, 2026 17:16

fix(release): verify smoke tests actually ran in nightly provenance c…

934546a

…heck (#911) Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

docs: remove em-dashes and fix the version-source binary in the relea…

8ce1f8b

…se runbook

norrietaylor marked this pull request as ready for review July 23, 2026 21:44

twitchyliquid64 approved these changes Jul 25, 2026

View reviewed changes

norrietaylor merged commit 09660c9 into main Jul 26, 2026
29 checks passed

norrietaylor deleted the pr/release-pipeline branch July 26, 2026 01:20

Navigation Menu

Uh oh!

docs: document the release and install pipeline - #867

docs: document the release and install pipeline#867
norrietaylor merged 6 commits into
mainfrom
pr/release-pipeline

norrietaylor commented Jul 21, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

Review limit reached

Uh oh!

Uh oh!

Uh oh!

macroscopeapp Bot Jul 22, 2026

Uh oh!

norrietaylor Jul 22, 2026

Uh oh!

macroscopeapp Bot Jul 22, 2026

Uh oh!

macroscopeapp Bot Jul 22, 2026

Uh oh!

macroscopeapp Bot Jul 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

norrietaylor commented Jul 21, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Verification

Note

Document the release pipeline and strengthen nightly provenance verification

Uh oh!

coderabbitai Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

Uh oh!

Uh oh!

macroscopeapp Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

norrietaylor Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

macroscopeapp Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

macroscopeapp Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

macroscopeapp Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jul 21, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading