Skip to content

Commit 4f18a80

Browse files
noreplyclaude
andcommitted
fork-follow: report from real state, guarded pushes, upstream workflows off
Review round 1 on the follow-upstream workflow. - The plan picks one of five actions: none, release, rebase, advance (the rebased series is already released; only move main) and stage (the rebase changes the release workflow itself, so the candidate is pushed and a person starts its release). - Merge commits on main are refused instead of being flattened by a rebase; deleted or moved upstream tags and failed fetches give a reason and the right advice. - All pushes go through fork-follow-push.sh with FORK_PUSH_TOKEN only. Every run checks the token first (missing, refused, no push access). Moving main uses a lease, treats "already there" as success, and first keeps the old series as tag fork-follow/pre-<tag>-<sha12>. - fork-workflows.sh disables upstream's workflows and cancels their runs after each push and at the end of the run. - The report job runs on every run and reads branches, tags and releases back from the repository instead of guessing from job results. Its summary is the report; an issue is opened, commented on or closed only when the repository has Issues enabled. - fork-follow.test.sh covers all of this against local git remotes and a fake gh, plus static checks on the workflow file (secrets passed by name, token only in push steps, persist-credentials false, pinned actions). The plan job runs it first. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 8c32db6 commit 4f18a80

6 files changed

Lines changed: 1116 additions & 113 deletions

File tree

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
#!/usr/bin/env bash
2+
# The pushes of fork-follow.yml, all made with FORK_PUSH_TOKEN, one subcommand each (tests:
3+
# fork-follow.test.sh). Every refusal writes its reason to $REPORT, prints a ::error:: line and
4+
# exits non-zero; nothing falls back to another token.
5+
#
6+
# check Fails unless FORK_PUSH_TOKEN is set, accepted by GitHub and may push here.
7+
# candidate SHA Force-pushes SHA as the branch fork-follow/candidate.
8+
# advance PREV SHA Moves SERIES_BRANCH from PREV to SHA with a lease. First keeps PREV as the tag
9+
# fork-follow/pre-<BASE_TAG>-<PREV, 12 hex>, so the old series stays reachable.
10+
# Already at SHA (a re-run) is success; moved elsewhere is a refusal.
11+
# cleanup Deletes the branch fork-follow/candidate; a failure is only a warning.
12+
#
13+
# Environment: FORK_PUSH_TOKEN, REPOSITORY (owner/name; GITHUB_REPOSITORY in a run), PUSH_URL
14+
# (default https://github.com/$REPOSITORY.git), SERIES_BRANCH (default main), BASE_TAG (advance),
15+
# REPORT. Output (candidate_pushed, moved, backup_tag) goes to $GITHUB_OUTPUT, else stdout.
16+
#
17+
# The token reaches git through GIT_CONFIG_* variables as an HTTP header: never in a URL, a command
18+
# line or .git/config, so git's error messages (copied into reports) cannot contain it.
19+
set -euo pipefail
20+
21+
REPOSITORY="${REPOSITORY:-${GITHUB_REPOSITORY:?REPOSITORY or GITHUB_REPOSITORY}}"
22+
PUSH_URL="${PUSH_URL:-https://github.com/$REPOSITORY.git}"
23+
SERIES_BRANCH="${SERIES_BRANCH:-main}"
24+
REPORT="${REPORT:-fork-follow-report.md}"
25+
OUTPUT="${GITHUB_OUTPUT:-/dev/stdout}"
26+
CANDIDATE_BRANCH=fork-follow/candidate
27+
err="$(mktemp)"
28+
trap 'rm -f "$err"' EXIT
29+
30+
die() {
31+
printf '%s\n' "$@" > "$REPORT"
32+
printf '::error::%s\n' "$1" >&2
33+
[[ $# -lt 2 ]] || printf '%s\n' "${@:2}" >&2
34+
exit 1
35+
}
36+
37+
git_said() { printf '%s\n' '```' "$(tail -n 15 "$err")" '```'; }
38+
39+
with_token() {
40+
[[ -n "${FORK_PUSH_TOKEN:-}" ]] \
41+
|| die "The secret FORK_PUSH_TOKEN is missing, so this run cannot push." \
42+
"Add it under Settings > Secrets and variables > Actions: a fine-grained token for $REPOSITORY only, with Contents and Workflows read and write." \
43+
"GITHUB_TOKEN cannot replace it: it may not push commits that change workflow files."
44+
local header
45+
header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$FORK_PUSH_TOKEN" | base64 -w0)"
46+
[[ "${GITHUB_ACTIONS:-}" != true ]] || echo "::add-mask::$header"
47+
export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.https://github.com/.extraheader GIT_CONFIG_VALUE_0="$header"
48+
export GIT_TERMINAL_PROMPT=0
49+
}
50+
51+
remote_ref() { # prints the remote's commit for a ref, or nothing; fails if the remote cannot be read
52+
git ls-remote "$PUSH_URL" "$1" 2> "$err" | cut -f1
53+
}
54+
55+
cmd_check() {
56+
with_token
57+
git ls-remote "$PUSH_URL" HEAD > /dev/null 2> "$err" \
58+
|| die "GitHub refused FORK_PUSH_TOKEN: it is expired, revoked, or not valid for $REPOSITORY." \
59+
"Renew it (a fine-grained token for $REPOSITORY only, Contents and Workflows read and write) and update the secret. git said:" \
60+
"$(git_said)"
61+
# A dry run asks for push access (receive-pack) without changing anything.
62+
git push --dry-run "$PUSH_URL" "$(git rev-parse HEAD):refs/heads/fork-follow/token-check" > /dev/null 2> "$err" \
63+
|| die "FORK_PUSH_TOKEN may not push to $REPOSITORY." \
64+
"Give the token Contents read and write (and Workflows read and write) on $REPOSITORY. git said:" "$(git_said)"
65+
echo "FORK_PUSH_TOKEN is accepted and may push to $REPOSITORY."
66+
}
67+
68+
cmd_candidate() {
69+
local sha="${1:?SHA}"
70+
with_token
71+
git push --force "$PUSH_URL" "$sha:refs/heads/$CANDIDATE_BRANCH" > /dev/null 2> "$err" \
72+
|| die "Could not push the candidate ${sha:0:12} to $CANDIDATE_BRANCH." \
73+
"If the rebase brought workflow file changes, the token also needs Workflows read and write. git said:" "$(git_said)"
74+
echo "candidate_pushed=true" >> "$OUTPUT"
75+
echo "Pushed ${sha:0:12} to $CANDIDATE_BRANCH."
76+
}
77+
78+
cmd_advance() {
79+
local prev="${1:?PREV}" sha="${2:?SHA}" now backup
80+
: "${BASE_TAG:?BASE_TAG}"
81+
with_token
82+
now="$(remote_ref "refs/heads/$SERIES_BRANCH")" \
83+
|| die "Could not read $SERIES_BRANCH of $REPOSITORY, so it was not moved. git said:" "$(git_said)"
84+
if [[ "$now" == "$sha" ]]; then
85+
echo "moved=already" >> "$OUTPUT"
86+
echo "$SERIES_BRANCH is already at ${sha:0:12}."
87+
return 0
88+
fi
89+
[[ "$now" == "$prev" ]] \
90+
|| die "$SERIES_BRANCH moved since the plan (now ${now:-missing}, planned from ${prev:0:12}), so it was not moved to ${sha:0:12}." \
91+
"A fork pull request merged meanwhile, or someone pushed it. The next run rebases again with that change."
92+
backup="fork-follow/pre-$BASE_TAG-${prev:0:12}"
93+
git push "$PUSH_URL" "$prev:refs/tags/$backup" > /dev/null 2> "$err" \
94+
|| die "Could not keep the old series ${prev:0:12} as tag $backup, so $SERIES_BRANCH was not moved. git said:" "$(git_said)"
95+
echo "backup_tag=$backup" >> "$OUTPUT"
96+
git push --force-with-lease="refs/heads/$SERIES_BRANCH:$prev" "$PUSH_URL" "$sha:refs/heads/$SERIES_BRANCH" > /dev/null 2> "$err" \
97+
|| die "Could not move $SERIES_BRANCH from ${prev:0:12} to ${sha:0:12}." \
98+
"If a rule protects $SERIES_BRANCH, the token's user must be allowed to bypass it. The old series is kept as tag $backup. git said:" "$(git_said)"
99+
echo "moved=true" >> "$OUTPUT"
100+
echo "Moved $SERIES_BRANCH from ${prev:0:12} to ${sha:0:12} (old series kept as tag $backup)."
101+
}
102+
103+
cmd_cleanup() {
104+
with_token
105+
local now
106+
if ! now="$(remote_ref "refs/heads/$CANDIDATE_BRANCH")"; then
107+
echo "::warning::Could not read $CANDIDATE_BRANCH; it may be left over (the next run force-pushes over it)."
108+
elif [[ -n "$now" ]] && ! git push "$PUSH_URL" --delete "refs/heads/$CANDIDATE_BRANCH" > /dev/null 2> "$err"; then
109+
echo "::warning::Could not delete $CANDIDATE_BRANCH (the next run force-pushes over it): $(tail -n 3 "$err" | tr '\n' ' ')"
110+
fi
111+
return 0
112+
}
113+
114+
case "${1:-}" in
115+
check) cmd_check ;;
116+
candidate) cmd_candidate "${@:2}" ;;
117+
advance) cmd_advance "${@:2}" ;;
118+
cleanup) cmd_cleanup ;;
119+
*) echo "usage: $0 check | candidate SHA | advance PREV SHA | cleanup" >&2; exit 2 ;;
120+
esac
Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
#!/usr/bin/env bash
2+
# Report job of fork-follow.yml (tests: fork-follow.test.sh). Writes the run's summary and exits
3+
# non-zero when the run needs a person, so trouble shows as a failed run even without issues.
4+
#
5+
# What was pushed and published is read back from the repository (branches, tags, releases), not
6+
# inferred from job results, so the summary never claims a state it did not see. When the
7+
# repository has Issues enabled it also opens or comments on one issue, "Fork cannot follow
8+
# upstream", and closes it once a run succeeds; with Issues disabled it says so and opens none.
9+
#
10+
# Environment (from the run): REPOSITORY, SERIES_BRANCH, RUN_URL, ACTION, PLAN_RESULT,
11+
# RELEASE_RESULT, ADVANCE_RESULT, BASE_TAG, PREVIOUS_TAG, PREVIOUS_HEAD, CANDIDATE, RELEASED_TAG,
12+
# DROPPED, DISABLED, CANCELLED (from the workflow sweeps), SWEEP_RESULT, REPORTS (directory of the jobs' reason
13+
# files), ORIGIN (git URL of this fork, default GitHub). Summary to $GITHUB_STEP_SUMMARY, else stdout.
14+
set -uo pipefail
15+
16+
REPOSITORY="${REPOSITORY:-${GITHUB_REPOSITORY:?REPOSITORY or GITHUB_REPOSITORY}}"
17+
ORIGIN="${ORIGIN:-https://github.com/$REPOSITORY.git}"
18+
SERIES_BRANCH="${SERIES_BRANCH:-main}"
19+
SUMMARY="${GITHUB_STEP_SUMMARY:-/dev/stdout}"
20+
ACTION="${ACTION:-}"
21+
REPORTS="${REPORTS:-}"
22+
title="Fork cannot follow upstream"
23+
short() { [[ -n "$1" ]] && echo "\`${1:0:12}\`" || echo "(none)"; }
24+
25+
failed=false
26+
for result in "${PLAN_RESULT:-}" "${RELEASE_RESULT:-skipped}" "${ADVANCE_RESULT:-skipped}"; do
27+
[[ "$result" == success || "$result" == skipped ]] || failed=true
28+
done
29+
[[ "${PLAN_RESULT:-}" == success ]] || failed=true
30+
[[ "$ACTION" != stage ]] || failed=true
31+
[[ "${SWEEP_RESULT:-success}" != failure ]] || failed=true
32+
33+
# The sweeps' lists arrive joined with ','; drop the empty parts and repeats.
34+
tidy() { tr ',' '\n' <<< "$1" | sed '/^$/d' | awk '!seen[$0]++' | paste -sd, -; }
35+
DISABLED="$(tidy "${DISABLED:-}")"
36+
CANCELLED="$(tidy "${CANCELLED:-}")"
37+
38+
state=()
39+
row() { state+=("| $1 | $2 |"); }
40+
41+
# --- what the repository holds now -----------------------------------------------------------
42+
if refs="$(git ls-remote "$ORIGIN" "refs/heads/$SERIES_BRANCH" refs/heads/fork-follow/candidate 'refs/tags/*' 2>&1)"; then
43+
at() { awk -v ref="$1" '$2 == ref { print $1 }' <<< "$refs"; }
44+
series_now="$(at "refs/heads/$SERIES_BRANCH")"
45+
candidate_now="$(at refs/heads/fork-follow/candidate)"
46+
if [[ -z "${CANDIDATE:-}" ]]; then
47+
row "Series branch \`$SERIES_BRANCH\`" "at $(short "$series_now")"
48+
elif [[ "$series_now" == "$CANDIDATE" && "${PREVIOUS_HEAD:-$CANDIDATE}" != "$CANDIDATE" ]]; then
49+
row "Series branch \`$SERIES_BRANCH\`" "moved to $(short "$CANDIDATE") (was $(short "$PREVIOUS_HEAD"))"
50+
elif [[ "$series_now" == "$CANDIDATE" ]]; then
51+
row "Series branch \`$SERIES_BRANCH\`" "at $(short "$series_now"), unchanged"
52+
else
53+
row "Series branch \`$SERIES_BRANCH\`" "**not moved**: at $(short "$series_now")"
54+
fi
55+
row "Candidate branch \`fork-follow/candidate\`" "$([[ -n "$candidate_now" ]] && echo "at $(short "$candidate_now")" || echo "absent")"
56+
backups="$(awk '$2 ~ "^refs/tags/fork-follow/pre-" && $2 !~ /\^\{\}$/ { sub("refs/tags/", "", $2); print $2 }' <<< "$refs" | paste -sd, -)"
57+
[[ -z "$backups" ]] || row "Backups of earlier series (tags)" "${backups//,/, }"
58+
# Fork release tags that point at the candidate (lightweight, or annotated and peeled).
59+
tags=""
60+
if [[ -n "${CANDIDATE:-}" ]]; then
61+
tags="$(awk -v sha="$CANDIDATE" '$1 == sha { t = $2; sub("refs/tags/", "", t); sub(/\^\{\}$/, "", t); print t }' <<< "$refs" \
62+
| grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-fork\.[0-9]+$' | sort -uV)"
63+
fi
64+
if [[ -z "${CANDIDATE:-}" ]]; then
65+
row "Release" "none: the plan did not pick a commit"
66+
elif [[ -z "$tags" ]]; then
67+
row "Release" "**none published** for $(short "$CANDIDATE")"
68+
else
69+
for tag in $tags; do
70+
if draft="$(gh api "repos/$REPOSITORY/releases/tags/$tag" --jq .draft 2>&1)"; then
71+
if [[ "$draft" == false ]]; then
72+
if [[ "$tag" == "${RELEASED_TAG:-}" && "$ACTION" != release ]]; then
73+
row "Release" "$tag, published earlier"
74+
else
75+
row "Release" "$tag **published** at $(short "$CANDIDATE")"
76+
fi
77+
else
78+
row "Release" "$tag tag exists, release is still a draft (not offered to updaters)"
79+
failed=true
80+
fi
81+
elif [[ "$draft" == *"Not Found"* || "$draft" == *"404"* ]]; then
82+
row "Release" "tag $tag exists without a release"
83+
failed=true
84+
else
85+
row "Release" "unknown: could not read the release of $tag"
86+
failed=true
87+
fi
88+
done
89+
fi
90+
else
91+
row "Repository state" "unknown: could not read the branches and tags of $REPOSITORY"
92+
failed=true
93+
fi
94+
[[ -z "${DISABLED:-}" ]] || row "Upstream workflows disabled" "${DISABLED//,/, }"
95+
[[ -z "${CANCELLED:-}" ]] || row "Their runs cancelled" "${CANCELLED//,/, }"
96+
[[ -z "${DROPPED:-}" ]] || row "Patches dropped (empty on $BASE_TAG: upstream has the change)" "${DROPPED//;/, }"
97+
98+
reasons=""
99+
if [[ -n "$REPORTS" && -d "$REPORTS" ]]; then
100+
for file in "$REPORTS"/*.md; do
101+
[[ -f "$file" ]] && reasons+="$(cat "$file")"$'\n\n'
102+
done
103+
fi
104+
105+
case "$ACTION" in
106+
none) what="Nothing to do: the series is released${RELEASED_TAG:+ as $RELEASED_TAG}." ;;
107+
release) what="Release the series on ${BASE_TAG:-?} as it is." ;;
108+
rebase) what="Rebase the series from ${PREVIOUS_TAG:-?} onto ${BASE_TAG:-?}, release it, then move \`$SERIES_BRANCH\`." ;;
109+
advance) what="Move \`$SERIES_BRANCH\` onto ${BASE_TAG:-?}: ${RELEASED_TAG:-?} already has the rebased series." ;;
110+
stage) what="Rebase onto ${BASE_TAG:-?} and push the candidate; its release needs its own workflow files." ;;
111+
*) what="The plan did not finish." ;;
112+
esac
113+
114+
body="$(mktemp)"
115+
{
116+
if [[ "$failed" == true ]]; then
117+
echo "## $title"
118+
else
119+
echo "## Fork follows upstream"
120+
fi
121+
echo
122+
echo "Plan: $what Run: ${RUN_URL:-?}"
123+
echo
124+
if [[ "$failed" == true ]]; then
125+
if [[ -n "$reasons" ]]; then
126+
printf '%s' "$reasons"
127+
else
128+
echo "A job failed without writing a reason (results: plan ${PLAN_RESULT:-?}, release ${RELEASE_RESULT:-skipped}, advance ${ADVANCE_RESULT:-skipped}); see the run."
129+
echo
130+
fi
131+
fi
132+
echo "| What | State now |"
133+
echo "|---|---|"
134+
printf '%s\n' "${state[@]}"
135+
} > "$body"
136+
137+
# --- the issue, when the repository has Issues ---------------------------------------------------
138+
note=""
139+
if ! has_issues="$(gh api "repos/$REPOSITORY" --jq .has_issues 2>&1)"; then
140+
note="Could not read whether $REPOSITORY has Issues, so no issue was opened or closed."
141+
failed=true
142+
elif [[ "$has_issues" != true ]]; then
143+
note="Issues are disabled on $REPOSITORY, so no issue was opened or closed; this summary and the run's status are the report."
144+
elif ! issue="$(gh issue list --repo "$REPOSITORY" --state open --search "\"$title\" in:title" \
145+
--json number,title --jq ".[] | select(.title == \"$title\") | .number" | head -n1)"; then
146+
note="Could not list the issues of $REPOSITORY, so no issue was opened or closed."
147+
failed=true
148+
elif [[ "$failed" == true && -n "$issue" ]]; then
149+
gh issue comment "$issue" --repo "$REPOSITORY" --body-file "$body" > /dev/null \
150+
&& note="Commented on issue #$issue." || { note="Could not comment on issue #$issue."; }
151+
elif [[ "$failed" == true ]]; then
152+
if url="$(gh issue create --repo "$REPOSITORY" --title "$title" --body-file "$body")"; then
153+
note="Opened $url."
154+
else
155+
note="Could not open an issue."
156+
fi
157+
elif [[ -n "$issue" ]]; then
158+
gh issue close "$issue" --repo "$REPOSITORY" --comment "$(cat "$body")" > /dev/null \
159+
&& note="Closed issue #$issue." || { note="Could not close issue #$issue."; failed=true; }
160+
fi
161+
162+
{
163+
cat "$body"
164+
[[ -z "$note" ]] || printf '\n%s\n' "$note"
165+
} >> "$SUMMARY"
166+
rm -f "$body"
167+
[[ "$failed" != true ]]

0 commit comments

Comments
 (0)