ci(promote): repoint docs rebuild dispatch to gominimal/webapp + docs-hotfix by norrietaylor · Pull Request #987 · gominimal/minimal

norrietaylor · 2026-07-27T22:22:23Z

Summary

The standalone docs host gominimal/docs (VitePress) was retired and collapsed into gominimal/webapp (Astro), which now runs the deploy-time docs sync restored in gominimal/webapp#489. That sync pulls docs/{reference,concepts,guide→start} from this repo at a resolved release sha and prerenders it.

This PR wires the upstream (this-repo) side of that mechanism:

promote.yml — repoint the reference-docs-promoted repository_dispatch and the AW_BOT token scope from gominimal/docs → gominimal/webapp. On promote, the resolved release sha is pushed as the dispatch payload; the webapp pulls docs at that sha.
docs-hotfix.yml (new) — a workflow_dispatch that fires the same reference-docs-promoted dispatch for a chosen sha (default main HEAD). This lets a docs correction go live on the webapp without cutting or promoting a binary release.

Resolves the upstream repoint tracked in gominimal/webapp#486 and gominimal/webapp#489's operator follow-up.

Prerequisites (operator / cross-repo — not code)

Sequence after webapp#489 (currently OPEN) — it adds the receiving reference-docs-promoted trigger. Until it merges, both dispatches are harmless no-ops.
Provision AW_BOT on gominimal/webapp with contents: write (AW_BOT_APP_ID var + AW_BOT_PRIVATE_KEY secret), or swap the mint step to the org APP_ID/APP_PRIVATE_KEY already on this repo. Without it the token-mint step fails. (webapp#489 operator follow-up.)
Durable-hotfix decision (non-blocking) — the webapp resolves the docs sha as MINIMAL_DOCS_SHA → stable → unstable → main. docs-hotfix.yml sets MINIMAL_DOCS_SHA for one deploy; a later webapp-driven deploy reverts to the channel pointer. So a hotfix is a bridge until the fix ships in the next promoted release. A durable alternative (a promote-written docs pointer the webapp reads first) needs a webapp-side change — tracked in webapp#486.

Verification

Both workflows parse as valid YAML; no residual gominimal/docs refs remain in .github/workflows/.
End-to-end (after prereqs 1–2): trigger docs-hotfix (or a dry-run promote) and confirm the webapp deploy resolves MINIMAL_DOCS_SHA and syncs the reference/concepts/guide sections at that sha.

.github/workflows/ is CODEOWNER-gated — this needs owner review before merge.

🤖 Generated with Claude Code

Note

Repoint docs rebuild dispatch to `gominimal/webapp` and add `docs-hotfix` workflow

Updates promote.yml to dispatch the reference-docs-promoted event to gominimal/webapp instead of gominimal/docs, including token scope and API endpoint.
Adds docs-hotfix.yml, a manually triggered workflow that dispatches reference-docs-promoted to gominimal/webapp with a specified or default SHA, without requiring a binary promotion.

Changes since #987 opened

Added SHA validation to the 'Resolve sha' step in the docs-hotfix workflow [fa112e5]

^{Macroscope summarized 062015d.}

Summary by CodeRabbit

Documentation
- Documentation rebuilds after CLI promotions are now dispatched to run through the web app.
- Added an optional manual documentation hotfix workflow to synchronize a selected source revision.
- Improved reliability by validating and using the correct commit revision when triggering documentation refreshes.

The standalone docs host (gominimal/docs) was collapsed into the webapp (gominimal/webapp#470), which now runs the deploy-time docs sync (gominimal/webapp#489). Repoint promote.yml's reference-docs-promoted dispatch and its bot-token scope from docs to webapp so promotions refresh docs on the live site. Add docs-hotfix.yml: a workflow_dispatch that fires the same reference-docs-promoted dispatch for a chosen sha (default main HEAD), so a docs correction can go live without cutting a binary release. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

coderabbitai · 2026-07-27T22:22:51Z

📝 Walkthrough

Walkthrough

Adds a manually triggered documentation hotfix workflow and redirects promotion-triggered documentation rebuild events from gominimal/docs to gominimal/webapp, passing the selected commit SHA through the repository event payload.

Changes

Documentation dispatch routing

Layer / File(s)	Summary
Manual and promotion documentation dispatch `.github/workflows/docs-hotfix.yml`, `.github/workflows/promote.yml`	The hotfix workflow resolves and validates an optional SHA, mints a webapp-scoped GitHub App token, and dispatches `reference-docs-promoted`; the promotion workflow now targets the same repository and payload.
Estimated code review effort: 2 (Simple)	~10 minutes

Possibly related PRs

gominimal/webapp#489 — Adds deploy-time handling for the reference-docs-promoted event and supplied SHA.

Suggested labels: github_actions

Poem

A rabbit taps the workflow bell,
Sends SHA parcels where docs dwell.
Tokens mint and events hop,
Webapp catches every drop.
“Thump-thump!” says Bunny, “Ship it well!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly states the main change: repoint docs rebuild dispatch to gominimal/webapp and add docs-hotfix.
Description check	✅ Passed	The description is detailed and covers summary, prerequisites, and verification, though it does not use the exact Testing/Checklist template sections.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

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

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/docs-hotfix.yml (1)
1-80: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Obtain @gominimal/minimalists approval for this workflow change. .github/workflows/docs-hotfix.yml is CODEOWNERS-protected, so this is a merge blocker until the required workflow-owner review is present.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docs-hotfix.yml around lines 1 - 80, Obtain and record the
required CODEOWNERS approval from `@gominimal/minimalists` for the workflow
changes in docs-hotfix.yml before merging; no code changes are needed.
Sources: Coding guidelines, Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.github/workflows/docs-hotfix.yml:
- Around line 1-80: Obtain and record the required CODEOWNERS approval from
`@gominimal/minimalists` for the workflow changes in docs-hotfix.yml before
merging; no code changes are needed.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 84b9bbb6-c237-437c-9ec4-9b14b37f4249

📥 Commits

Reviewing files that changed from the base of the PR and between f633a2a and 062015d.

📒 Files selected for processing (2)

.github/workflows/docs-hotfix.yml
.github/workflows/promote.yml

agent-137 · 2026-07-27T22:33:19Z

Non-blocking nit on docs-hotfix.yml: the sha input is trimmed but not validated before dispatch. The webapp side does validate (SHA_RE in scripts/sync-docs.ts) and falls back to the channel pointer with a ::warning::, so junk input degrades safely — but it still burns a full webapp deploy to accomplish nothing. A fail-fast guard in the resolve step would catch it upstream:

[[ "$SHA" =~ ^[0-9a-f]{7,40}$ ]] || { echo "::error::not a commit sha: ${SHA}"; exit 1; }

Everything else verified against the receiver in webapp#489 — event type and client_payload.sha match exactly, and the sequencing note is right (both dispatches are no-ops until it merges).

Reject non-sha input in the resolve step before dispatching, instead of burning a webapp deploy that degrades to the channel pointer. Addresses review on #987. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

norrietaylor · 2026-07-27T22:52:25Z

Good call — applied in fa112e5e. The resolve step now rejects anything that isn't a 7–40 char hex sha (after the empty→github.sha default) with a ::error:: and non-zero exit, so junk fails before the dispatch instead of costing a webapp deploy. Thanks for cross-checking the event type / client_payload.sha against the webapp#489 receiver.

mitodrummer approved these changes Jul 27, 2026

View reviewed changes

coderabbitai Bot reviewed Jul 27, 2026

View reviewed changes

ci(docs-hotfix): fail fast on a malformed sha input

fa112e5

Reject non-sha input in the resolve step before dispatching, instead of burning a webapp deploy that degrades to the channel pointer. Addresses review on #987. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

norrietaylor merged commit ccf8ba3 into main Jul 27, 2026
29 checks passed

norrietaylor deleted the ci/promote-docs-repoint-webapp branch July 27, 2026 23:36

Navigation Menu

Uh oh!

ci(promote): repoint docs rebuild dispatch to gominimal/webapp + docs-hotfix - #987

ci(promote): repoint docs rebuild dispatch to gominimal/webapp + docs-hotfix#987
norrietaylor merged 2 commits into
mainfrom
ci/promote-docs-repoint-webapp

norrietaylor commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 27, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

agent-137 commented Jul 27, 2026

Uh oh!

norrietaylor commented Jul 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

Summary

Prerequisites (operator / cross-repo — not code)

Verification

Repoint docs rebuild dispatch to gominimal/webapp and add docs-hotfix workflow

Changes since #987 opened

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

agent-137 commented Jul 27, 2026

Uh oh!

norrietaylor commented Jul 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

norrietaylor commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading

Repoint docs rebuild dispatch to `gominimal/webapp` and add `docs-hotfix` workflow

coderabbitai Bot commented Jul 27, 2026 •

edited

Loading