Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
norrietaylor merged 2 commits into from
Jul 27, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
062015d
ci(promote): repoint docs rebuild dispatch to gominimal/webapp
norrietaylor Jul 27, 2026
fa112e5
ci(docs-hotfix): fail fast on a malformed sha input
norrietaylor Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions .github/workflows/docs-hotfix.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
name: docs-hotfix

# Refresh the public docs on gominimal/webapp from a chosen gominimal/minimal
# sha WITHOUT cutting or promoting a binary release. Use this to push a docs
# correction live between releases.
#
# Mechanism: the webapp's deploy-time sync (gominimal/webapp
# deploy-cloudrun.yml, restored in gominimal/webapp#489) resolves the docs sha
# in priority order MINIMAL_DOCS_SHA -> stable channel -> unstable channel ->
# main. A `reference-docs-promoted` repository_dispatch sets MINIMAL_DOCS_SHA
# from client_payload.sha, so this workflow pins that deploy to the given sha
# and syncs the allow-listed doc sections (reference/, concepts/, guide->start/)
# at it.
#
# Scope / durability: this triggers ONE webapp deploy at the chosen sha. A later
# webapp deploy that is not driven by this dispatch falls back to the channel
# pointer, so a hotfix is a bridge until the fix ships in the next promoted
# release (after which the channel pointer carries it durably).

on:
workflow_dispatch:
inputs:
sha:
description: "gominimal/minimal sha to sync docs from (empty = this workflow's ref)"
required: false
type: string
default: ""

permissions:
contents: read

concurrency:
group: docs-hotfix
cancel-in-progress: false

jobs:
dispatch:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Resolve sha
id: resolve
env:
INPUT_SHA: ${{ inputs.sha }}
REF_SHA: ${{ github.sha }}
run: |
set -euo pipefail
# Trim stray whitespace; SHAs are often pasted with spaces.
SHA="$(printf '%s' "$INPUT_SHA" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
# Default to the ref this workflow runs from (main HEAD).
[ -z "$SHA" ] && SHA="$REF_SHA"
# Fail fast on a malformed sha. The webapp validates too and
# degrades to the channel pointer, but only after burning a full
# deploy — cheaper to reject junk here before dispatching.
[[ "$SHA" =~ ^[0-9a-f]{7,40}$ ]] || { echo "::error::not a commit sha: ${SHA}"; exit 1; }
echo "sha=${SHA}" >> "$GITHUB_OUTPUT"
echo "Docs hotfix will pin gominimal/webapp to ${SHA}"

# Mint a short-lived token scoped to gominimal/webapp via the
# gominimal-aw-bot GitHub App (org standard — App tokens over PATs,
# see gominimal/min-aw ADR-0002). The default GITHUB_TOKEN cannot
# dispatch other repos; this token carries the App's contents:write
# permission narrowed to the webapp repo only.
- name: Mint webapp-repo token (gominimal-aw-bot)
id: webapp-token
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
with:
app-id: ${{ vars.AW_BOT_APP_ID }}
private-key: ${{ secrets.AW_BOT_PRIVATE_KEY }}
owner: gominimal
repositories: webapp

- name: Dispatch reference-docs-promoted
env:
GH_TOKEN: ${{ steps.webapp-token.outputs.token }}
SHA: ${{ steps.resolve.outputs.sha }}
run: |
set -euo pipefail
gh api repos/gominimal/webapp/dispatches \
-f event_type=reference-docs-promoted \
-F "client_payload[sha]=${SHA}"
echo "Dispatched reference-docs-promoted to gominimal/webapp for ${SHA}"
16 changes: 9 additions & 7 deletions .github/workflows/promote.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,20 +232,22 @@ jobs:
# Export resolved SHA for the docs-rebuild dispatch step below.
echo "sha=${SHA}" >> "$GITHUB_OUTPUT"

# Mint a short-lived token scoped to gominimal/docs via the
# Mint a short-lived token scoped to gominimal/webapp via the
# gominimal-aw-bot GitHub App (org standard — App tokens over PATs, see
# gominimal/min-aw ADR-0002). The default GITHUB_TOKEN cannot dispatch
# other repos; this token carries the App's contents:write permission
# narrowed to the docs repo only.
- name: Mint docs-repo token (gominimal-aw-bot)
# narrowed to the webapp repo only. The standalone docs host was
# collapsed into the webapp (gominimal/webapp#470), which now runs the
# deploy-time docs sync, so promotions dispatch the rebuild there.
- name: Mint webapp-repo token (gominimal-aw-bot)
id: docs-token
if: ${{ inputs.dry_run != true }}
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
with:
app-id: ${{ vars.AW_BOT_APP_ID }}
private-key: ${{ secrets.AW_BOT_PRIVATE_KEY }}
owner: gominimal
repositories: docs
repositories: webapp

- name: Trigger docs rebuild
env:
Expand All @@ -255,10 +257,10 @@ jobs:
run: |
set -euo pipefail
if [ "$DRY_RUN" = "true" ]; then
echo "[dry-run] would dispatch reference-docs-promoted to gominimal/docs for ${SHA}"
echo "[dry-run] would dispatch reference-docs-promoted to gominimal/webapp for ${SHA}"
else
gh api repos/gominimal/docs/dispatches \
gh api repos/gominimal/webapp/dispatches \
-f event_type=reference-docs-promoted \
-F "client_payload[sha]=${SHA}"
echo "Dispatched reference-docs-promoted to gominimal/docs for ${SHA}"
echo "Dispatched reference-docs-promoted to gominimal/webapp for ${SHA}"
fi