@jagreehal/shepherd 0.3.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.
- package/AGENTS.md +5 -0
- package/README.md +40 -419
- package/lenses/observability/SKILL.md +18 -11
- package/package.json +16 -8
- package/skills/ci-repair/SKILL.md +6 -1
- package/skills/garden/SKILL.md +28 -3
- package/skills/garden/references/telemetry.md +50 -0
- package/skills/incident/SKILL.md +6 -1
- package/skills/shepherd/SKILL.md +95 -1
- package/skills/shepherd/references/dispatch.md +12 -0
- package/skills/shepherd/references/stories.md +102 -0
- package/skills/swarm/SKILL.md +5 -0
- package/skills/triage/SKILL.md +19 -0
- package/src/cli.ts +117 -6
- package/src/garden-traces.ts +461 -0
- package/src/garden.ts +2 -1
- package/src/install.ts +3 -0
- package/src/notify.ts +138 -0
- package/src/trace.ts +180 -0
- package/templates/shepherd-incident.yml +156 -0
- package/templates/shepherd.yml +399 -0
|
@@ -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
|