@jagreehal/shepherd 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,399 @@
1
+ # shepherd in CI: one loop iteration each time CI or stamp finishes on a PR, on a `/shepherd` comment,
2
+ # when a PR gets the SHEPHERD_LABEL, or from the sweep. Each iteration's fixes are pushed, CI and stamp run
3
+ # on the new head, and their completion starts the next one, until shepherd sets a final `shepherd` status
4
+ # (success, or failure naming what the author must do). Installed by `shepherd workflows`.
5
+ #
6
+ # The model reads text anyone can write (comments, review threads, bot output), so it never holds a write
7
+ # credential. `gate` (no model) decides whether to run. `iterate` runs the model with github.token, which can
8
+ # comment, resolve threads and read, never push; its commits leave as a git bundle. `publish` runs no model:
9
+ # it pushes the bundle to the PR's own branch only as a fast-forward that touches nothing matching
10
+ # SHEPHERD_PUSH_DENY, then sets the status and notifies.
11
+ #
12
+ # Secrets:
13
+ # SHEPHERD_TOKEN fine-grained PAT: contents, pull requests and commit statuses (read/write). Only
14
+ # `gate` and `publish` see it. Pushes made with github.token start no workflows, so the loop would stall.
15
+ # OPENCODE_API_KEY the models (any provider: set the matching key and SHEPHERD_MODEL).
16
+ # SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
17
+ # you, is ready to merge, or the iteration stopped on an error.
18
+ # Variables:
19
+ # SHEPHERD_MODEL provider/model for opencode; empty = opencode-go/kimi-k3.
20
+ # SHEPHERD_LABEL optional: shepherd only PRs carrying this label. Whatever opens PRs (a person, Claude
21
+ # Code, Codex, another agent) hands one over by adding it.
22
+ # SHEPHERD_NOTIFY_ON optional: states that notify, e.g. "failure"; empty = success,failure,error.
23
+ # SHEPHERD_PUSH_DENY optional: extended regex of paths a handed-off fix may not touch; empty = workflows,
24
+ # git and editor hooks, package manager config, manifests and lockfiles.
25
+ #
26
+ # Edit `workflows: [ci, stamp]` to name your CI workflow. workflow_run, pull_request_target and schedule
27
+ # run this file from the default branch, so a PR cannot change how it is shepherded.
28
+ name: shepherd
29
+ on:
30
+ workflow_run:
31
+ workflows: [ci, stamp]
32
+ types: [completed]
33
+ issue_comment:
34
+ types: [created]
35
+ pull_request_target:
36
+ types: [labeled]
37
+ workflow_dispatch:
38
+ inputs:
39
+ pr:
40
+ description: PR number
41
+ required: true
42
+ schedule:
43
+ - cron: "*/30 * * * *" # the sweep: PRs left pending with nothing to wake them (bot reviews, a lost event)
44
+
45
+ permissions:
46
+ contents: read
47
+
48
+ # One run per PR at a time, gate to publish, so a run's statuses never interleave with another's. The condition
49
+ # is the gate's `if` verbatim (a test keeps them in step): a run that event alone rules out gets a group of its
50
+ # own. A run the gate step skips after reading GitHub (finished head, label scope, incident branch) still queues
51
+ # in the PR's group, where GitHub keeps one waiting run, so a later event can take a queued `/shepherd`'s place.
52
+ concurrency:
53
+ group: >-
54
+ ${{ github.event_name == 'schedule' && 'shepherd-sweep'
55
+ || (((github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.pull_requests[0] != null && github.event.workflow_run.head_repository.full_name == github.repository) || (github.event_name == 'issue_comment' && github.event.issue.pull_request != null && startsWith(github.event.comment.body, '/shepherd') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) || (github.event_name == 'pull_request_target' && vars.SHEPHERD_LABEL != '' && github.event.label.name == vars.SHEPHERD_LABEL) || github.event_name == 'workflow_dispatch') && format('shepherd-{0}', github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr))
56
+ || format('shepherd-skip-{0}', github.run_id) }}
57
+ cancel-in-progress: false # a run may be mid-handoff; later triggers queue, and GitHub keeps only the newest
58
+
59
+ jobs:
60
+ sweep:
61
+ if: github.event_name == 'schedule'
62
+ runs-on: ubuntu-latest
63
+ timeout-minutes: 5
64
+ permissions:
65
+ actions: write # workflow_dispatch of this file, one run per PR
66
+ statuses: read
67
+ pull-requests: read
68
+ env:
69
+ GH_TOKEN: ${{ github.token }}
70
+ LABEL: ${{ vars.SHEPHERD_LABEL }}
71
+ steps:
72
+ - name: Start an iteration on each PR still pending
73
+ run: |
74
+ # With a label, a labelled PR shepherd has never touched counts as pending too.
75
+ wf=$(basename "${GITHUB_WORKFLOW_REF%@*}")
76
+ gh pr list -R "$GITHUB_REPOSITORY" --state open --limit 100 --json number,headRefOid,isDraft,isCrossRepository,labels \
77
+ --jq '.[] | select(.isDraft | not) | select(.isCrossRepository | not) | [.number, .headRefOid, ([.labels[].name] | join(","))] | @tsv' |
78
+ while IFS=$'\t' read -r pr head labels; do
79
+ if [ -n "$LABEL" ]; then [[ ",$labels," == *",$LABEL,"* ]] || continue; fi
80
+ state=$(gh api "repos/$GITHUB_REPOSITORY/commits/$head/status" --jq '[.statuses[] | select(.context=="shepherd")][0].state // ""')
81
+ if [ "$state" = pending ] || { [ -z "$state" ] && [ -n "$LABEL" ]; }; then
82
+ echo "dispatch #$pr (${state:-untouched})"
83
+ gh workflow run "$wf" -R "$GITHUB_REPOSITORY" -f pr="$pr"
84
+ fi
85
+ done
86
+
87
+ # Runs no model. The only job that reads SHEPHERD_TOKEN besides publish: a secret any step of a job uses sits
88
+ # in that job's runner memory, where a hijacked model step could read it.
89
+ gate:
90
+ if: >-
91
+ (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'pull_request'
92
+ && github.event.workflow_run.pull_requests[0] != null
93
+ && github.event.workflow_run.head_repository.full_name == github.repository)
94
+ || (github.event_name == 'issue_comment' && github.event.issue.pull_request != null
95
+ && startsWith(github.event.comment.body, '/shepherd')
96
+ && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
97
+ || (github.event_name == 'pull_request_target' && vars.SHEPHERD_LABEL != ''
98
+ && github.event.label.name == vars.SHEPHERD_LABEL)
99
+ || github.event_name == 'workflow_dispatch'
100
+ runs-on: ubuntu-latest
101
+ timeout-minutes: 5
102
+ permissions:
103
+ contents: read
104
+ pull-requests: read
105
+ statuses: write # pending before the model starts
106
+ outputs:
107
+ run: ${{ steps.gate.outputs.run }}
108
+ branch: ${{ steps.gate.outputs.branch }}
109
+ base: ${{ steps.gate.outputs.base }}
110
+ head: ${{ steps.gate.outputs.head }}
111
+ git_name: ${{ steps.gate.outputs.git_name }}
112
+ git_email: ${{ steps.gate.outputs.git_email }}
113
+ env:
114
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
115
+ LABEL: ${{ vars.SHEPHERD_LABEL }}
116
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
117
+ MAX_SHEPHERD_COMMITS: 20
118
+ steps:
119
+ - name: Decide whether this iteration is worth running
120
+ id: gate
121
+ env:
122
+ GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
123
+ run: |
124
+ [[ "$PR" =~ ^[0-9]+$ ]] || { echo "PR must be a number"; exit 1; }
125
+ pr=$(gh pr view "$PR" -R "$GITHUB_REPOSITORY" --json state,author,headRefOid,headRefName,baseRefName,isCrossRepository,isDraft,labels,commits)
126
+ state=$(jq -r .state <<<"$pr"); head=$(jq -r .headRefOid <<<"$pr"); author=$(jq -r .author.login <<<"$pr"); branch=$(jq -r .headRefName <<<"$pr")
127
+ skip() { echo "skip: $1"; echo "run=false" >> "$GITHUB_OUTPUT"; exit 0; }
128
+ [ "$state" = OPEN ] || skip "PR is $state"
129
+ [ "$(jq -r .isCrossRepository <<<"$pr")" = false ] || skip "fork PR"
130
+ [ "$(jq -r .isDraft <<<"$pr")" = false ] || skip "draft"
131
+ # publish pushes to the head branch: never let that be the default branch.
132
+ [ "$branch" != "$DEFAULT_BRANCH" ] || skip "the PR's head is the default branch"
133
+ labelled=false
134
+ [ -n "$LABEL" ] && jq -e --arg l "$LABEL" 'any(.labels[]; .name == $l)' <<<"$pr" >/dev/null && labelled=true
135
+ # A label scopes the automatic triggers; a /shepherd comment always runs.
136
+ if [ -n "$LABEL" ] && [ "$GITHUB_EVENT_NAME" != issue_comment ] && [ "$labelled" = false ]; then skip "no $LABEL label"; fi
137
+ # An incident fix was written by an agent from alert text. A person starts shepherd on it.
138
+ if [[ "$branch" == incident/* ]] && [ "$GITHUB_EVENT_NAME" != issue_comment ] && [ "$labelled" = false ]; then
139
+ skip "incident fix: comment /shepherd${LABEL:+ or add the $LABEL label} to start"
140
+ fi
141
+ # Only PRs by people who could push this code themselves: shepherd runs their checks with these secrets.
142
+ perm=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$author/permission" --jq .permission 2>/dev/null || echo none)
143
+ case "$perm" in admin|maintain|write) ;; *) skip "author $author has $perm access" ;; esac
144
+ if [ "$GITHUB_EVENT_NAME" = workflow_run ] || { [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$GITHUB_ACTOR" = "github-actions[bot]" ]; }; then
145
+ done=$(gh api "repos/$GITHUB_REPOSITORY/commits/$head/status" --jq '[.statuses[] | select(.context=="shepherd")][0].state // ""')
146
+ case "$done" in success|failure|error) skip "shepherd already finished on $head ($done); comment /shepherd to run again" ;; esac
147
+ # The sweep dispatched this run for a pending head; a run that finished it while this one queued wins.
148
+ if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ] && [ "$done" != pending ] && { [ -n "$done" ] || [ -z "$LABEL" ]; }; then skip "head is no longer pending"; fi
149
+ fi
150
+ n=$(jq '[.commits[] | select(.messageBody | test("^Shepherd: "; "m"))] | length' <<<"$pr")
151
+ if [ "$n" -ge "$MAX_SHEPHERD_COMMITS" ]; then
152
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$head" -f context=shepherd -f state=failure -f description="stopped after $n shepherd commits; a person should look" >/dev/null || true
153
+ skip "$n shepherd commits"
154
+ fi
155
+ # Commits go out under the token's owner, as their own pushes would.
156
+ login=$(gh api user --jq .login 2>/dev/null || true)
157
+ if [ -n "$login" ]; then
158
+ echo "git_name=$login" >> "$GITHUB_OUTPUT"
159
+ echo "git_email=$(gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"')" >> "$GITHUB_OUTPUT"
160
+ else
161
+ echo "git_name=github-actions[bot]" >> "$GITHUB_OUTPUT"
162
+ echo "git_email=41898282+github-actions[bot]@users.noreply.github.com" >> "$GITHUB_OUTPUT"
163
+ fi
164
+ { echo "run=true"; echo "branch=$branch"; echo "base=$(jq -r .baseRefName <<<"$pr")"; echo "head=$head"; } >> "$GITHUB_OUTPUT"
165
+ # A rerun must never leave an old green standing while the model works or after it fails.
166
+ - name: Mark the head pending
167
+ if: steps.gate.outputs.run == 'true'
168
+ env:
169
+ GH_TOKEN: ${{ github.token }}
170
+ HEAD_SHA: ${{ steps.gate.outputs.head }}
171
+ run: gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state=pending -f description="shepherd iteration running" >/dev/null
172
+
173
+ iterate:
174
+ needs: gate
175
+ if: needs.gate.outputs.run == 'true'
176
+ runs-on: ubuntu-latest
177
+ timeout-minutes: 45
178
+ # github.token for the model: comment, resolve threads, read code and CI. No contents write, and no
179
+ # SHEPHERD_TOKEN anywhere in this job.
180
+ permissions:
181
+ contents: read
182
+ pull-requests: write
183
+ issues: write
184
+ actions: read
185
+ checks: read
186
+ statuses: read
187
+ env:
188
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
189
+ SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
190
+ steps:
191
+ - uses: actions/checkout@v4
192
+ with:
193
+ ref: ${{ needs.gate.outputs.branch }}
194
+ fetch-depth: 0
195
+ persist-credentials: false # no token in .git/config for the model to find
196
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the model key
197
+ # Install your project's dependencies here so shepherd's checks can run, with install scripts off and no
198
+ # dependency cache (npm ci --ignore-scripts; setup-node without `cache:`): a cache this job saves would
199
+ # reach every later run on the default branch.
200
+ - shell: bash # -eo pipefail: a failed download fails here, not in the agent step
201
+ env:
202
+ GIT_NAME: ${{ needs.gate.outputs.git_name }}
203
+ GIT_EMAIL: ${{ needs.gate.outputs.git_email }}
204
+ run: |
205
+ # The pinned CLI on PATH: the skills call `shepherd`, and fall back to an unpinned bunx without it.
206
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
207
+ export PATH="$HOME/.bun/bin:$PATH" && echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
208
+ [ "$(command -v shepherd)" = "$HOME/.bun/bin/shepherd" ] || { echo "shepherd is not the pinned CLI"; exit 1; }
209
+ shepherd install # skills to ~/.claude/skills, where opencode finds them
210
+ # OpenCode 1.x: its installer refuses 2.x releases, which have their own (opencode.ai/v2/install).
211
+ curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.0
212
+ "$HOME/.opencode/bin/opencode" --version # fails the step if the install did not land
213
+ echo "$HOME/.opencode/bin" >> "$GITHUB_PATH"
214
+ git config user.name "$GIT_NAME"
215
+ git config user.email "$GIT_EMAIL"
216
+ mkdir -p "$RUNNER_TEMP/handoff"
217
+ - name: One shepherd iteration
218
+ timeout-minutes: 30 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
219
+ env:
220
+ GH_TOKEN: ${{ github.token }}
221
+ SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
222
+ OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
223
+ OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
224
+ OPENCODE_DISABLE_AUTOUPDATE: "1"
225
+ MODEL: ${{ vars.SHEPHERD_MODEL || 'opencode-go/kimi-k3' }}
226
+ run: |
227
+ opencode run --auto -m "$MODEL" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
228
+ SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. You are running in GitHub Actions on the PR branch,
229
+ already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
230
+ would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
231
+ iterations; the next one starts when CI or stamp finishes on the head the workflow pushes."
232
+ - name: Bundle the commits
233
+ env:
234
+ H0: ${{ needs.gate.outputs.head }}
235
+ run: |
236
+ git branch -f shepherd-handoff HEAD
237
+ if [ "$(git rev-parse HEAD)" != "$H0" ]; then git bundle create "$RUNNER_TEMP/handoff/fix.bundle" "$H0..shepherd-handoff"; fi
238
+ - uses: actions/upload-artifact@v4
239
+ with:
240
+ name: shepherd-handoff
241
+ path: ${{ runner.temp }}/handoff
242
+ if-no-files-found: ignore
243
+
244
+ publish:
245
+ needs: [gate, iterate]
246
+ # The finalizer: runs whether the iteration succeeded or not, so a failed or timed-out model leaves an
247
+ # `error` status, never the pending the gate set or an older green.
248
+ if: always() && needs.gate.result == 'success' && needs.gate.outputs.run == 'true'
249
+ runs-on: ubuntu-latest
250
+ timeout-minutes: 10
251
+ # No model runs here, and nothing the model wrote runs here: the bundle is fetched and checked, never executed.
252
+ permissions:
253
+ contents: read
254
+ pull-requests: read
255
+ statuses: write
256
+ actions: write # rerun the jobs ci-repair asked for
257
+ env:
258
+ PR: ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr }}
259
+ BRANCH: ${{ needs.gate.outputs.branch }}
260
+ BASE: ${{ needs.gate.outputs.base }}
261
+ H0: ${{ needs.gate.outputs.head }}
262
+ HAS_PAT: ${{ secrets.SHEPHERD_TOKEN != '' }}
263
+ ITERATED: ${{ needs.iterate.result }}
264
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
265
+ # Paths that run without review: CI, git and editor hooks, package manager config, manifests and lockfiles.
266
+ # Matched case-insensitively.
267
+ DENY: ${{ vars.SHEPHERD_PUSH_DENY || '^\.github/|^\.gitmodules$|(^|/)\.gitattributes$|(^|/)\.(husky|githooks|devcontainer|vscode)/|(^|/)\.(npmrc|yarnrc|yarnrc\.yml|pnpmfile\.cjs)$|(^|/)(package\.json|bunfig\.toml|go\.mod|cargo\.toml|build\.rs|pyproject\.toml|setup\.(py|cfg)|requirements[^/]*\.txt|gemfile|composer\.json|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|[^/]*\.lockb?|[^/]*[._-]lock\.(json|ya?ml|hcl|toml)|[^/]*\.lockfile|npm-shrinkwrap\.json|go\.sum|package\.resolved|(gnu)?makefile|\.?justfile|taskfile(\.dist)?\.ya?ml)$|(^|/)\.pre-commit-config\.yaml$|(^|/)\.cargo/|(^|/)(pnpm-workspace\.yaml|pipfile|deno\.jsonc?)$' }}
268
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in iterate
269
+ steps:
270
+ # First, before any setup that could fail: a stopped iteration must never leave the gate's pending standing.
271
+ - name: Report a stopped iteration
272
+ id: stopped
273
+ if: env.ITERATED != 'success'
274
+ env:
275
+ GH_TOKEN: ${{ github.token }}
276
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
277
+ run: |
278
+ echo "shepherd iteration ${ITERATED}; comment /shepherd to retry" > description.txt
279
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$H0" -f context=shepherd -f state=error -f description="$(cat description.txt)" -f target_url="$RUN_URL" >/dev/null
280
+ echo "state=error" >> "$GITHUB_OUTPUT"
281
+ - if: env.ITERATED == 'success'
282
+ uses: actions/download-artifact@v4
283
+ id: handoff
284
+ continue-on-error: true # no artifact: the iteration wrote nothing
285
+ with:
286
+ name: shepherd-handoff
287
+ path: handoff
288
+ - if: env.ITERATED == 'success'
289
+ uses: actions/checkout@v4
290
+ with:
291
+ ref: ${{ needs.gate.outputs.branch }}
292
+ fetch-depth: 0
293
+ path: repo
294
+ token: ${{ secrets.SHEPHERD_TOKEN || github.token }}
295
+ - name: Push the handed-off commits
296
+ id: push
297
+ if: env.ITERATED == 'success'
298
+ working-directory: repo
299
+ shell: bash # -eo pipefail
300
+ env:
301
+ GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
302
+ run: |
303
+ echo "head=$H0" >> "$GITHUB_OUTPUT"
304
+ refuse() { echo "::error::$1"; echo "refused=$1" >> "$GITHUB_OUTPUT"; exit 0; }
305
+ [ -f ../handoff/fix.bundle ] || { echo "no commits handed off"; exit 0; }
306
+ [ "$HAS_PAT" = true ] || refuse "set the SHEPHERD_TOKEN secret so shepherd can push"
307
+ [ "$BRANCH" != "$DEFAULT_BRANCH" ] && [ "$BRANCH" != "$BASE" ] || refuse "will not push to $BRANCH"
308
+ git -c core.hooksPath=/dev/null fetch -q ../handoff/fix.bundle "shepherd-handoff:refs/shepherd/handoff"
309
+ new=$(git rev-parse refs/shepherd/handoff)
310
+ live=$(gh pr view "$PR" -R "$GITHUB_REPOSITORY" --json headRefOid -q .headRefOid)
311
+ [ "$live" = "$H0" ] || { echo "someone pushed ($H0 -> $live); the next iteration re-baselines"; echo "stale=true" >> "$GITHUB_OUTPUT"; exit 0; }
312
+ git merge-base --is-ancestor "$H0" "$new" || refuse "the fixes are not a fast-forward of $H0"
313
+ # A path counts when the fixes left it different from both the head they started on and the base, so a
314
+ # base merge's own changes pass. NUL-delimited and rename-free: no quoted or renamed path slips by.
315
+ git diff -z --no-renames --name-only "$H0" "$new" > ../from-head
316
+ git diff -z --no-renames --name-only "origin/$BASE" "$new" > ../from-base
317
+ bad=$(python3 - ../from-head ../from-base "$DENY" <<'PY'
318
+ import re, sys
319
+ read = lambda f: {p for p in open(f, "rb").read().split(b"\0") if p}
320
+ deny = re.compile(sys.argv[3].encode(), re.IGNORECASE)
321
+ # A control character in a path is refused outright: no tool needs one, and it can split a line.
322
+ bad = sorted(p for p in read(sys.argv[1]) & read(sys.argv[2]) if deny.search(p) or re.search(rb"[\x00-\x1f\x7f]", p))
323
+ # Paths are model-chosen: no control character reaches GITHUB_OUTPUT or a workflow command.
324
+ print(" ".join(re.sub(r"[\x00-\x1f\x7f]", "?", p.decode(errors="replace")) for p in bad)[:500])
325
+ PY
326
+ )
327
+ [ -z "$bad" ] || refuse "the fixes touch protected paths: $bad"
328
+ git -c core.hooksPath=/dev/null push origin "$new:refs/heads/$BRANCH"
329
+ { echo "head=$new"; echo "pushed=$(git rev-list --count "$H0..$new")"; } >> "$GITHUB_OUTPUT"
330
+ - name: Set the shepherd status
331
+ id: status
332
+ if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true'
333
+ env:
334
+ GH_TOKEN: ${{ github.token }}
335
+ HEAD_SHA: ${{ steps.push.outputs.head }}
336
+ PUSHED: ${{ steps.push.outputs.pushed }}
337
+ REFUSED: ${{ steps.push.outputs.refused }}
338
+ run: |
339
+ # status.json is model output: only a known state and one short line of text get through.
340
+ python3 - handoff/status.json "$PUSHED" "$REFUSED" > status.out <<'PY'
341
+ import json, sys
342
+ try:
343
+ s = json.load(open(sys.argv[1]))
344
+ except Exception:
345
+ s = {}
346
+ if not isinstance(s, dict):
347
+ s = {}
348
+ state = s.get("state") if s.get("state") in ("success", "pending", "failure") else "pending"
349
+ desc = " ".join(str(s.get("description") or "iteration ended without a status").split())
350
+ if sys.argv[3]:
351
+ state, desc = "failure", f"fixes not pushed, a person should look: {' '.join(sys.argv[3].split())}"
352
+ elif sys.argv[2]:
353
+ state, desc = "pending", f"pushed {sys.argv[2]} commit(s) for review; {desc}"
354
+ print(state)
355
+ print(desc[:139])
356
+ PY
357
+ state=$(sed -n 1p status.out); sed -n 2p status.out > description.txt
358
+ gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state="$state" -f description="$(cat description.txt)" >/dev/null
359
+ echo "state=$state" >> "$GITHUB_OUTPUT"
360
+ - name: Rerun the jobs ci-repair asked for
361
+ if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && steps.push.outputs.pushed == '' && hashFiles('handoff/rerun-jobs.txt') != ''
362
+ env:
363
+ GH_TOKEN: ${{ github.token }}
364
+ run: |
365
+ # Model output names the jobs: rerun one only if it ran on this PR's head from a pull_request event.
366
+ grep -E '^[0-9]+$' handoff/rerun-jobs.txt | head -10 | while read -r job; do
367
+ run=$(gh api "repos/$GITHUB_REPOSITORY/actions/jobs/$job" --jq 'select(.head_sha == env.H0) | .run_id' 2>/dev/null || true)
368
+ event=$([ -n "$run" ] && gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run" --jq .event 2>/dev/null || true)
369
+ if [ "$event" = pull_request ]; then
370
+ gh run rerun --job "$job" -R "$GITHUB_REPOSITORY" || echo "could not rerun job $job"
371
+ else
372
+ echo "skip job $job: not a pull_request job on $H0"
373
+ fi
374
+ done
375
+ # Only notify needs the CLI: a failed install here can skip a notification, never a status.
376
+ - if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success'
377
+ uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the write token
378
+ - if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success'
379
+ shell: bash
380
+ run: |
381
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
382
+ echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
383
+ - name: Notify
384
+ if: steps.status.outcome == 'success' || steps.stopped.outcome == 'success' # from the workspace, not the PR checkout
385
+ env:
386
+ GH_TOKEN: ${{ github.token }}
387
+ HEAD_SHA: ${{ steps.push.outputs.head || needs.gate.outputs.head }}
388
+ STATE: ${{ steps.status.outputs.state || steps.stopped.outputs.state }}
389
+ SHEPHERD_NOTIFY_WEBHOOK: ${{ secrets.SHEPHERD_NOTIFY_WEBHOOK }}
390
+ SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
391
+ run: shepherd notify --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$HEAD_SHA" --state "$STATE" --file description.txt
392
+ # Any step above failing (checkout, push, status) must not leave the gate's pending for the sweep to rerun.
393
+ - name: Report a failed publish
394
+ if: always() && failure()
395
+ env:
396
+ GH_TOKEN: ${{ github.token }}
397
+ HEAD_SHA: ${{ steps.push.outputs.head || needs.gate.outputs.head }}
398
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
399
+ run: gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state=error -f description="shepherd could not publish this iteration; see the run, then comment /shepherd" -f target_url="$RUN_URL" >/dev/null