* ci(autofix): push bot fixes with a scoped GitHub App token
github-actions[bot] pushes left PR checks action_required instead of
retriggering, and the DOCS_AUTOFIX_TOKEN fallback secret was never
configured. bazel-autofix.yml and docs-autofix.yml now mint a short-lived,
repo-scoped (contents:write) installation token for the gastownhall-autofix
App via the `autofix` environment on same-repo PRs, falling back to the
default workflow token (and its manual re-run note) when the App token
isn't available; fork PRs are unaffected and still only get the apply-recipe
comment.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* test(ci): job environment parses as a name or a mapping; gofmt
ciWorkflowJob.Environment was a string, so every test that loads all
workflows failed on deploy-pages-redirect.yml's mapping form
(environment: {name, url}).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
386 lines
16 KiB
Bash
Executable file
386 lines
16 KiB
Bash
Executable file
#!/usr/bin/env bash
|
|
# docs-autofix-push.sh - apply a CI-generated CLI docs regeneration patch to a
|
|
# PR branch, or fall back to an instructive PR comment when pushing is not
|
|
# possible.
|
|
#
|
|
# Runs on the PRIVILEGED side of the docs-autofix workflow_run pipeline: the
|
|
# checkout is always the base repository's default branch (trusted code), and
|
|
# the patch produced by the unprivileged PR build is treated as UNTRUSTED DATA.
|
|
# Confinement is layered:
|
|
# * the path allowlist below pins WHICH files a patch may name (anchored
|
|
# regexes, single path segment, no traversal);
|
|
# * any mode line, symlink, rename/copy or binary hunk is refused, so only
|
|
# regular 100644 files are created, edited or deleted;
|
|
# * the patch is applied to an index only (`git read-tree` + `git apply
|
|
# --cached` in a bare clone): the PR tree is never written to disk, and
|
|
# git's own guards reject `..`/absolute paths and in-patch symlinks;
|
|
# * the staged result is re-checked against the same allowlist.
|
|
# A hostile patch can therefore at most rewrite generated doc files on its own
|
|
# PR branch.
|
|
#
|
|
# Usage:
|
|
# docs-autofix-push.sh validate, then push or comment (env below)
|
|
# docs-autofix-push.sh --check P validate patch P only; exit 0 if acceptable
|
|
#
|
|
# Inputs (environment):
|
|
# BASE_REPO base "owner/name" (e.g. gastownhall/beads)
|
|
# HEAD_REPO PR head "owner/name" (same as BASE_REPO for branch PRs;
|
|
# may be empty if the head fork was deleted)
|
|
# HEAD_BRANCH PR head branch name
|
|
# HEAD_SHA head commit the failing run was built from
|
|
# PATCH_FILE path to the downloaded cli-docs-freshness.patch
|
|
# RUN_ID workflow run id that produced the patch (for comment text)
|
|
# RUN_URL html url of that run (for commit/comment provenance)
|
|
# GH_TOKEN token for gh api calls (PR lookup, comments) - needs the
|
|
# workflow's pull-requests:write; never the App token
|
|
# PUSH_TOKEN token for git fetch/push only (optional; defaults to
|
|
# GH_TOKEN), so the minted gastownhall-autofix App token
|
|
# needs contents:write only
|
|
# AUTOFIX_TOKEN_KIND "app" when the minted App push token is in use,
|
|
# "default" for the workflow's GITHUB_TOKEN (retrigger
|
|
# caveat)
|
|
#
|
|
# Exit 0 on every non-actionable outcome (PR closed, head moved, no patch);
|
|
# exit 1 on a refused patch or a genuine error so the workflow surfaces them.
|
|
|
|
set -euo pipefail
|
|
export LC_ALL=C
|
|
# Nothing from the PR tree may run: no LFS smudge, no prompts.
|
|
export GIT_LFS_SKIP_SMUDGE=1 GIT_TERMINAL_PROMPT=0
|
|
|
|
COMMENT_MARKER="<!-- cli-docs-autofix -->"
|
|
AUTOFIX_SUBJECT="docs: auto-regenerate CLI reference"
|
|
# Comments are only ever edited when this account wrote them: anyone can post
|
|
# a comment that starts with the marker.
|
|
COMMENT_AUTHOR="github-actions[bot]"
|
|
|
|
# Files the doc generators may write - keep in sync with GEN_PATHSPECS in
|
|
# scripts/check-cli-docs-drift.sh. Anchored, single path segment where a
|
|
# wildcard appears, conservative filename charset: no traversal, no nesting,
|
|
# no metacharacters can slip through.
|
|
path_allowed() {
|
|
case "$1" in *..*) return 1 ;; esac
|
|
[[ "$1" == "docs/CLI_REFERENCE.md" ]] && return 0
|
|
[[ "$1" == "docs/docs.json" ]] && return 0
|
|
[[ "$1" =~ ^docs/cli-reference/[A-Za-z0-9_.-]+\.md$ ]] && return 0
|
|
return 1
|
|
}
|
|
|
|
# Every git call: no hooks, whatever config a clone might carry.
|
|
git_() {
|
|
git -c core.hooksPath=/dev/null -c core.fsmonitor=false "$@"
|
|
}
|
|
|
|
# validate_patch FILE: refuse anything but plain text edits to regular files
|
|
# that path_allowed accepts. Shared verbatim with bazel-autofix-push.sh
|
|
# (scripts/ci_workflow_test.go checks), which documents each rule.
|
|
validate_patch() {
|
|
local file="$1" line path names bad="" count=0
|
|
# No mode change, symlink, rename or copy, binary hunk. ANY line starting
|
|
# "rename " or "copy " is refused: git apply also accepts the legacy
|
|
# "rename old"/"rename new" headers, which name a second path.
|
|
if grep -qE '^(old mode|new mode|similarity index|dissimilarity index|rename |copy |GIT binary patch|Binary files )' "$file"; then
|
|
echo "REFUSED: patch contains a mode change, rename/copy or binary hunk."
|
|
return 1
|
|
fi
|
|
if grep -E '^(new file mode|deleted file mode) ' "$file" | grep -qvE '^(new file mode|deleted file mode) 100644$'; then
|
|
echo "REFUSED: patch creates or deletes a non-regular (symlink/executable/submodule) file."
|
|
return 1
|
|
fi
|
|
# Every index line, whatever its ids look like, must be "index A..B" or
|
|
# "index A..B 100644"; a malformed id cannot hide a mode from this check.
|
|
if grep -E '^index ' "$file" | grep -qvE '^index [0-9a-f]+\.\.[0-9a-f]+( 100644)?$'; then
|
|
echo "REFUSED: patch has an index line that is not a regular 100644 file."
|
|
return 1
|
|
fi
|
|
# --summary is git's own view of creations, deletions, renames, copies,
|
|
# mode changes and rewrites; only 100644 creations/deletions may appear.
|
|
if ! names="$(git apply --summary "$file")"; then
|
|
echo "REFUSED: git apply cannot parse the patch."
|
|
return 1
|
|
fi
|
|
while IFS= read -r line; do
|
|
case "$line" in
|
|
"") continue ;;
|
|
" create mode 100644 "*) path="${line# create mode 100644 }" ;;
|
|
" delete mode 100644 "*) path="${line# delete mode 100644 }" ;;
|
|
*)
|
|
echo "REFUSED: patch summary has an unexpected entry: $line"
|
|
return 1
|
|
;;
|
|
esac
|
|
path_allowed "$path" || bad="${bad} ${path}\n"
|
|
done <<<"$names"
|
|
# --numstat -z prints "added<TAB>deleted<TAB>NAME<NUL>" with NAME raw
|
|
# (never quoted) and, for a rename, only the NEW name - hence the header
|
|
# and --summary checks above. The last read field keeps any tab/newline.
|
|
names="$(mktemp)"
|
|
if ! git apply --numstat -z "$file" >"$names"; then
|
|
rm -f "$names"
|
|
echo "REFUSED: git apply cannot parse the patch."
|
|
return 1
|
|
fi
|
|
while IFS=$'\t' read -r -d '' _ _ path; do
|
|
count=$((count + 1))
|
|
path_allowed "$path" || bad="${bad} ${path}\n"
|
|
done <"$names"
|
|
rm -f "$names"
|
|
if [ "$count" -eq 0 ]; then
|
|
echo "REFUSED: patch names no files."
|
|
return 1
|
|
fi
|
|
if [ -n "$bad" ]; then
|
|
printf 'REFUSED: patch touches paths outside the allowlist:\n%b' "$bad"
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# check_staged COMMIT: the index (after git apply --cached) differs from
|
|
# COMMIT only by regular-file adds/edits/deletes of allowlisted paths. Sets
|
|
# STAGED_PATHS. Shared verbatim with bazel-autofix-push.sh.
|
|
check_staged() {
|
|
local base="$1" meta path raw src_mode dst_mode status err=""
|
|
STAGED_PATHS=()
|
|
raw="$(mktemp)"
|
|
# -z --raw records: ":SRCMODE DSTMODE SRCSHA DSTSHA STATUS<NUL>PATH<NUL>".
|
|
git_ diff-index --cached --raw --no-renames -z "$base" >"$raw"
|
|
while IFS= read -r -d '' meta && IFS= read -r -d '' path; do
|
|
read -r src_mode dst_mode _ _ status <<<"$meta"
|
|
case "$src_mode $dst_mode $status" in
|
|
":100644 100644 M" | ":000000 100644 A" | ":100644 000000 D") ;;
|
|
*) err="REFUSED: staged change is not a regular-file edit: $meta $path" && break ;;
|
|
esac
|
|
if ! path_allowed "$path"; then
|
|
err="REFUSED: staged change outside the allowlist: $meta $path" && break
|
|
fi
|
|
STAGED_PATHS+=("$path")
|
|
done <"$raw"
|
|
rm -f -- "$raw"
|
|
if [ -n "$err" ]; then
|
|
echo "$err"
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
if [ "${1:-}" = "--check" ]; then
|
|
[ -s "${2:-}" ] || { echo "usage: $0 --check <patch>" >&2; exit 2; }
|
|
validate_patch "$2"
|
|
echo "OK: patch touches only generated CLI docs."
|
|
exit 0
|
|
fi
|
|
|
|
if [ -z "${HEAD_REPO:-}" ] || [ -z "${HEAD_BRANCH:-}" ]; then
|
|
echo "Head repository/branch unavailable (deleted fork?); nothing to do."
|
|
exit 0
|
|
fi
|
|
: "${BASE_REPO:?}" "${HEAD_SHA:?}"
|
|
: "${PATCH_FILE:?}" "${RUN_ID:?}" "${RUN_URL:?}" "${GH_TOKEN:?}"
|
|
AUTOFIX_TOKEN_KIND="${AUTOFIX_TOKEN_KIND:-default}"
|
|
PUSH_TOKEN="${PUSH_TOKEN:-$GH_TOKEN}"
|
|
|
|
if [ ! -s "$PATCH_FILE" ]; then
|
|
echo "No patch content; nothing to do."
|
|
exit 0
|
|
fi
|
|
PATCH_FILE="$(readlink -f "$PATCH_FILE")"
|
|
if ! [[ "$HEAD_SHA" =~ ^[0-9a-f]{40}$ ]]; then
|
|
echo "HEAD_SHA is not a commit id: $HEAD_SHA" >&2
|
|
exit 1
|
|
fi
|
|
|
|
# --- Validate the untrusted patch --------------------------------------------
|
|
|
|
validate_patch "$PATCH_FILE"
|
|
|
|
# --- Resolve the PR and confirm the patch is still current -------------------
|
|
|
|
# List-and-filter client side: branch names with URL metacharacters would
|
|
# corrupt a ?head= query string, and jq --arg needs no encoding. The PR must
|
|
# target this repository. One head branch can back several open PRs (into
|
|
# different bases); this artifact names no PR, so an ambiguous match is
|
|
# skipped rather than guessed.
|
|
PULLS_JSON="$(gh api --paginate "repos/$BASE_REPO/pulls?state=open&per_page=100")"
|
|
PR_MATCH="$(printf '%s' "$PULLS_JSON" | jq -r -s --arg repo "$HEAD_REPO" --arg branch "$HEAD_BRANCH" --arg base "$BASE_REPO" \
|
|
'add | [ .[] | select(.head.ref == $branch and (.head.repo.full_name // "") == $repo
|
|
and (.base.repo.full_name // "") == $base) ]
|
|
| if length == 1 then .[0] | "\(.number)\t\(.head.sha)" else "\(length)" end')"
|
|
case "$PR_MATCH" in
|
|
0)
|
|
echo "No open PR for $HEAD_REPO:$HEAD_BRANCH into $BASE_REPO; nothing to do."
|
|
exit 0
|
|
;;
|
|
*$'\t'*) IFS=$'\t' read -r PR_NUMBER PR_HEAD_NOW <<<"$PR_MATCH" ;;
|
|
*)
|
|
echo "$PR_MATCH open PRs use $HEAD_REPO:$HEAD_BRANCH; not guessing which one this patch is for."
|
|
exit 0
|
|
;;
|
|
esac
|
|
if [ "$PR_HEAD_NOW" != "$HEAD_SHA" ]; then
|
|
echo "PR #$PR_NUMBER head moved ($HEAD_SHA -> $PR_HEAD_NOW); a newer run owns the fix."
|
|
exit 0
|
|
fi
|
|
|
|
# post_or_update_comment BODY_FILE: edit our own marker comment, else post.
|
|
# Shared verbatim with bazel-autofix-push.sh.
|
|
post_or_update_comment() {
|
|
local body_file="$1"
|
|
# Capture fully before taking the first id: head -1 on a live --paginate
|
|
# stream SIGPIPEs gh under pipefail.
|
|
local ids existing
|
|
ids="$(gh api --paginate "repos/$BASE_REPO/issues/$PR_NUMBER/comments" \
|
|
--jq ".[] | select(.user.login == \"$COMMENT_AUTHOR\" and (.body | startswith(\"$COMMENT_MARKER\"))) | .id")"
|
|
existing="$(printf '%s\n' "$ids" | head -1)"
|
|
if [ -n "$existing" ]; then
|
|
gh api --method PATCH "repos/$BASE_REPO/issues/comments/$existing" \
|
|
-F body=@"$body_file" >/dev/null
|
|
echo "Updated autofix comment $existing on PR #$PR_NUMBER."
|
|
else
|
|
gh api --method POST "repos/$BASE_REPO/issues/$PR_NUMBER/comments" \
|
|
-F body=@"$body_file" >/dev/null
|
|
echo "Posted autofix comment on PR #$PR_NUMBER."
|
|
fi
|
|
}
|
|
|
|
# head_branch_protected: true unless GitHub itself says HEAD_BRANCH has no
|
|
# branch protection and no ruleset; an API error counts as protected. The name
|
|
# list is a floor, not the check. Shared verbatim with bazel-autofix-push.sh.
|
|
head_branch_protected() {
|
|
local enc protected rules
|
|
case "$HEAD_BRANCH" in
|
|
main | release/* | gh-readonly-queue/*) return 0 ;;
|
|
esac
|
|
enc="$(jq -rn --arg b "$HEAD_BRANCH" '$b | @uri')"
|
|
protected="$(gh api "repos/$BASE_REPO/branches/$enc" --jq '.protected' 2>/dev/null)" || return 0
|
|
[ "$protected" = "false" ] || return 0
|
|
rules="$(gh api "repos/$BASE_REPO/rules/branches/$enc" --jq 'length' 2>/dev/null)" || return 0
|
|
[ "$rules" = "0" ] || return 0
|
|
return 1
|
|
}
|
|
|
|
comment_fallback() {
|
|
local reason="$1"
|
|
local body
|
|
body="$(mktemp)"
|
|
cat > "$body" <<EOF
|
|
$COMMENT_MARKER
|
|
**Generated CLI docs are stale on this PR** (${reason}).
|
|
|
|
CI already produced the exact fix with its canonical pinned build. Apply it locally:
|
|
|
|
\`\`\`bash
|
|
gh run download $RUN_ID -R $BASE_REPO -n cli-docs-freshness-patch
|
|
git apply --index cli-docs-freshness.patch
|
|
git commit -m "docs: regenerate CLI reference"
|
|
git push
|
|
\`\`\`
|
|
|
|
Or regenerate from scratch: \`CGO_ENABLED=0 go build -tags gms_pure_go -o ./bd-docs ./cmd/bd/ && ./scripts/generate-cli-docs.sh ./bd-docs && rm ./bd-docs\`
|
|
|
|
_Automated by the [docs-autofix workflow]($RUN_URL); this comment is updated in place on each failing run._
|
|
EOF
|
|
post_or_update_comment "$body"
|
|
rm -f "$body"
|
|
}
|
|
|
|
# --- Fork PRs: no token we hold can push there, leave the recipe --------------
|
|
|
|
if [ "$HEAD_REPO" != "$BASE_REPO" ]; then
|
|
comment_fallback "fork PR - CI cannot push the fix to your branch"
|
|
exit 0
|
|
fi
|
|
|
|
# Never push to a protected branch or one under a ruleset, even if a PR uses
|
|
# it as head: the push token may be able to bypass what the author cannot.
|
|
if head_branch_protected; then
|
|
comment_fallback "the head branch $HEAD_BRANCH is protected from bot pushes"
|
|
exit 0
|
|
fi
|
|
|
|
# --- Same-repo PRs: push the regen commit -------------------------------------
|
|
|
|
# Keep the token out of on-disk .git/config: pass the auth header per command.
|
|
# Uses PUSH_TOKEN (the optional contents:write PAT), not the API token.
|
|
AUTH_CONFIG="http.https://github.com/.extraheader=AUTHORIZATION: basic $(printf 'x-access-token:%s' "$PUSH_TOKEN" | base64 -w0)"
|
|
|
|
WORK="$(mktemp -d)"
|
|
trap 'rm -rf "$WORK"' EXIT
|
|
# Bare clone and a private index: the PR tree is never checked out, so no
|
|
# symlink, .gitattributes or hook from it touches the disk.
|
|
export GIT_INDEX_FILE="$WORK/index"
|
|
|
|
# Only the head branch, blobs on demand: other branches' history never
|
|
# reaches the runner.
|
|
git_ init --quiet --bare "$WORK/repo.git"
|
|
cd "$WORK/repo.git"
|
|
git_ remote add origin "https://github.com/${BASE_REPO}.git"
|
|
git_ config remote.origin.promisor true
|
|
git_ config remote.origin.partialclonefilter blob:none
|
|
git_ -c "$AUTH_CONFIG" fetch --quiet --no-tags --filter=blob:none origin \
|
|
"+refs/heads/$HEAD_BRANCH:refs/autofix/head"
|
|
if ! git_ cat-file -e "$HEAD_SHA^{commit}" 2>/dev/null; then
|
|
echo "Head $HEAD_SHA no longer reachable on $BASE_REPO/$HEAD_BRANCH; skipping."
|
|
exit 0
|
|
fi
|
|
|
|
git_ read-tree "$HEAD_SHA"
|
|
if ! git_ -c "$AUTH_CONFIG" apply --cached "$PATCH_FILE" 2>/dev/null; then
|
|
cd /
|
|
comment_fallback "the regeneration patch no longer applies cleanly"
|
|
exit 0
|
|
fi
|
|
|
|
# Belt and braces: what actually got staged must pass the same rules.
|
|
check_staged "$HEAD_SHA"
|
|
if [ "${#STAGED_PATHS[@]}" -eq 0 ]; then
|
|
echo "Patch changes nothing on $HEAD_SHA; nothing to push."
|
|
exit 0
|
|
fi
|
|
|
|
# Circuit breaker, once the fix is known to be non-empty: if the failing head
|
|
# is already one of our autofix commits, regeneration is not converging (or
|
|
# something keeps dirtying the docs) - stacking more bot commits would loop.
|
|
# Read from the fetched commit (no API); failing to read it counts as
|
|
# non-convergent.
|
|
if ! HEAD_SUBJECT="$(git_ log -1 --format=%s "$HEAD_SHA")" || [[ "$HEAD_SUBJECT" == "$AUTOFIX_SUBJECT"* ]]; then
|
|
echo "Head $HEAD_SHA is (or may be) an autofix commit; refusing to stack another."
|
|
cd / && comment_fallback "the previous auto-regeneration commit left the docs stale - please regenerate manually"
|
|
exit 0
|
|
fi
|
|
|
|
TREE="$(git_ write-tree)"
|
|
NEW_SHA="$(GIT_AUTHOR_NAME="github-actions[bot]" GIT_COMMITTER_NAME="github-actions[bot]" \
|
|
GIT_AUTHOR_EMAIL="41898282+github-actions[bot]@users.noreply.github.com" \
|
|
GIT_COMMITTER_EMAIL="41898282+github-actions[bot]@users.noreply.github.com" \
|
|
git_ commit-tree "$TREE" -p "$HEAD_SHA" -m "$AUTOFIX_SUBJECT
|
|
|
|
Applied from the cli-docs-freshness-patch artifact of $RUN_URL
|
|
(generated with CI's canonical pinned build). See
|
|
scripts/check-cli-docs-drift.sh for how drift is attributed.")"
|
|
|
|
# Leased to HEAD_SHA: if the branch moved at all since the run (including a
|
|
# force-push back to an ancestor), the push is refused rather than resurrecting
|
|
# commits the author dropped.
|
|
if ! git_ -c "$AUTH_CONFIG" push --quiet \
|
|
"--force-with-lease=refs/heads/$HEAD_BRANCH:$HEAD_SHA" \
|
|
origin "$NEW_SHA:refs/heads/$HEAD_BRANCH"; then
|
|
cd /
|
|
comment_fallback "pushing the fix to $HEAD_BRANCH failed (branch protection or a concurrent push)"
|
|
exit 0
|
|
fi
|
|
cd /
|
|
|
|
echo "Pushed regen commit $NEW_SHA to $BASE_REPO/$HEAD_BRANCH."
|
|
|
|
BODY="$(mktemp)"
|
|
cat > "$BODY" <<EOF
|
|
$COMMENT_MARKER
|
|
**Pushed \`${NEW_SHA:0:12}\` regenerating the stale CLI docs**, from the canonical-build patch of the [failing run]($RUN_URL).
|
|
EOF
|
|
if [ "$AUTOFIX_TOKEN_KIND" = "default" ]; then
|
|
cat >> "$BODY" <<'EOF'
|
|
|
|
Note: this commit was pushed with the default workflow token, which does **not** retrigger PR checks - re-run them (or push any commit) to refresh the gate. This only happens if the gastownhall-autofix App token could not be minted for this push.
|
|
EOF
|
|
fi
|
|
post_or_update_comment "$BODY"
|
|
rm -f "$BODY"
|