@jagreehal/shepherd 0.3.0 → 0.5.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.
Files changed (55) hide show
  1. package/AGENTS.md +5 -0
  2. package/README.md +41 -419
  3. package/THIRD_PARTY_NOTICES.md +11 -0
  4. package/lenses/dotnet/SKILL.md +32 -0
  5. package/lenses/go/SKILL.md +30 -0
  6. package/lenses/java/SKILL.md +31 -0
  7. package/lenses/nextjs/SKILL.md +33 -0
  8. package/lenses/node-api/SKILL.md +32 -0
  9. package/lenses/nx-monorepo/SKILL.md +30 -0
  10. package/lenses/observability/SKILL.md +18 -11
  11. package/lenses/owasp-asvs/SKILL.md +50 -0
  12. package/lenses/owasp-llm/SKILL.md +44 -0
  13. package/lenses/python/SKILL.md +32 -0
  14. package/lenses/react/SKILL.md +33 -0
  15. package/lenses/rust/SKILL.md +31 -0
  16. package/package.json +17 -8
  17. package/packs/dotnet.yml +6 -0
  18. package/packs/go.yml +6 -0
  19. package/packs/java.yml +6 -0
  20. package/packs/nextjs.yml +7 -0
  21. package/packs/node-api.yml +7 -0
  22. package/packs/nx-monorepo.yml +6 -0
  23. package/packs/observability.yml +6 -0
  24. package/packs/owasp-asvs.yml +6 -0
  25. package/packs/owasp-llm.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +6 -1
  30. package/skills/garden/SKILL.md +28 -3
  31. package/skills/garden/references/telemetry.md +50 -0
  32. package/skills/incident/SKILL.md +6 -1
  33. package/skills/lens-import/SKILL.md +185 -0
  34. package/skills/lens-import/references/conversion.md +96 -0
  35. package/skills/lens-import/scripts/check-import.mjs +154 -0
  36. package/skills/shepherd/SKILL.md +121 -6
  37. package/skills/shepherd/references/dispatch.md +12 -0
  38. package/skills/shepherd/references/models.md +20 -7
  39. package/skills/shepherd/references/policy.md +9 -5
  40. package/skills/shepherd/references/stories.md +102 -0
  41. package/skills/swarm/SKILL.md +16 -1
  42. package/skills/swarm/references/custom-lenses.md +50 -7
  43. package/skills/triage/SKILL.md +19 -0
  44. package/src/cli.ts +210 -16
  45. package/src/config.ts +137 -21
  46. package/src/garden-traces.ts +461 -0
  47. package/src/garden.ts +2 -1
  48. package/src/install.ts +3 -0
  49. package/src/lens.ts +159 -8
  50. package/src/notify.ts +138 -0
  51. package/src/stack.ts +121 -0
  52. package/src/trace.ts +180 -0
  53. package/templates/shepherd-audit.yml +178 -0
  54. package/templates/shepherd-incident.yml +180 -0
  55. package/templates/shepherd.yml +427 -0
@@ -0,0 +1,178 @@
1
+ # shepherd audit in CI: a scheduled whole-repository security audit that runs plays from the OWASP Secure Agent
2
+ # Playbook (github.com/OWASP/secure-agent-playbook, CC-BY-4.0) on the default branch. Per-PR review stays with
3
+ # the owasp-asvs and owasp-llm lenses; these plays read the whole tree and run scanners, so they run weekly.
4
+ # Installed by `shepherd workflows --audit`.
5
+ #
6
+ # The agent's job reads the repository and writes a report, nothing more: no write credential, no persisted
7
+ # checkout token. A report carrying a credential shape is withheld before anything is uploaded. The report
8
+ # job runs no model and files or updates one `shepherd-audit` issue on a private repository. On a public
9
+ # repository issues and artifacts are public, so the audit runs there only when AUDIT_PUBLIC is `true`: the
10
+ # report then becomes a public artifact.
11
+ #
12
+ # Secrets: SHEPHERD_API_KEY (or the provider's own key) for the model.
13
+ # Variables: SHEPHERD_MODEL (a model or tier; empty = the team's models.loop or top rung), AWS_REGION (Bedrock),
14
+ # AUDIT_PLAYS (space-separated play names; empty = the default below),
15
+ # AUDIT_PUBLIC (`true` to run on a public repository, publishing the report).
16
+ name: shepherd-audit
17
+ on:
18
+ schedule:
19
+ - cron: "17 6 * * 1" # Mondays 06:17 UTC
20
+ workflow_dispatch:
21
+ inputs:
22
+ plays:
23
+ description: Plays to run, space-separated (empty = AUDIT_PLAYS or the default)
24
+ required: false
25
+
26
+ permissions: {}
27
+
28
+ jobs:
29
+ repo:
30
+ # Visibility and default branch from the API, so a scheduled run reads the same values as a manual one.
31
+ runs-on: ubuntu-latest
32
+ permissions:
33
+ contents: read
34
+ outputs:
35
+ private: ${{ steps.repo.outputs.private }}
36
+ default_branch: ${{ steps.repo.outputs.default_branch }}
37
+ steps:
38
+ - id: repo
39
+ shell: bash
40
+ env:
41
+ GH_TOKEN: ${{ github.token }}
42
+ run: gh api "repos/$GITHUB_REPOSITORY" --jq '"private=\(.private)\ndefault_branch=\(.default_branch)"' >> "$GITHUB_OUTPUT"
43
+
44
+ audit:
45
+ needs: repo
46
+ if: needs.repo.outputs.private == 'true' || vars.AUDIT_PUBLIC == 'true'
47
+ runs-on: ubuntu-latest
48
+ timeout-minutes: 60
49
+ concurrency:
50
+ group: shepherd-audit
51
+ cancel-in-progress: false
52
+ permissions:
53
+ contents: read
54
+ env:
55
+ SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
56
+ PLAYBOOK_SHA: 65d4efd2cd0b081d52101e9708792b944e4ddebb # OWASP/secure-agent-playbook, pinned: the plays are instructions
57
+ PLAYS: ${{ github.event.inputs.plays || vars.AUDIT_PLAYS || 'secrets-scan sca-audit iac-security-review code-review-security' }}
58
+ steps:
59
+ - uses: actions/checkout@v4
60
+ with:
61
+ ref: ${{ needs.repo.outputs.default_branch }}
62
+ fetch-depth: 0 # secrets-scan reads history
63
+ persist-credentials: false
64
+ - uses: actions/checkout@v4
65
+ with:
66
+ repository: OWASP/secure-agent-playbook
67
+ ref: ${{ env.PLAYBOOK_SHA }}
68
+ path: .shepherd-playbook # checkout writes only inside the workspace; moved out below
69
+ persist-credentials: false
70
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the model key
71
+ # Install your project's dependencies here if sca-audit should read the resolved tree, with install scripts
72
+ # off and no dependency cache (npm ci --ignore-scripts; setup-node without `cache:`): this job runs the model.
73
+ - shell: bash # -eo pipefail: a failed download fails here, not three steps later
74
+ run: |
75
+ mv "$GITHUB_WORKSPACE/.shepherd-playbook" "$RUNNER_TEMP/playbook" # out of the repository tree, so the plays never read as its content
76
+ for play in $PLAYS; do
77
+ [[ "$play" =~ ^[a-z0-9-]+$ ]] || { echo "::error::play names are lowercase with dashes: $play"; exit 1; }
78
+ ls "$RUNNER_TEMP"/playbook/plugins/*/plays/"$play.md" >/dev/null 2>&1 || { echo "::error::no play named $play at $PLAYBOOK_SHA"; exit 1; }
79
+ done
80
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
81
+ echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
82
+ curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.0 # 1.x: this installer refuses 2.x
83
+ "$HOME/.opencode/bin/opencode" --version # fails the step if the install did not land
84
+ echo "$HOME/.opencode/bin" >> "$GITHUB_PATH"
85
+ mkdir -p "$RUNNER_TEMP/audit"
86
+ - name: Audit
87
+ timeout-minutes: 45 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
88
+ env:
89
+ GH_TOKEN: ${{ github.token }}
90
+ SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
91
+ OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
92
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
93
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
94
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
95
+ DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
96
+ GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
97
+ MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
98
+ GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
99
+ XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
100
+ AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
101
+ AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
102
+ SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
103
+ SHEPHERD_DEFAULT_BRANCH: ${{ needs.repo.outputs.default_branch }}
104
+ OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md stay out of the agent's config
105
+ OPENCODE_DISABLE_AUTOUPDATE: "1"
106
+ run: |
107
+ # The team's models, from the default branch: the session model, the variable its key goes in, and the
108
+ # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
109
+ plan=$(shepherd ci-models)
110
+ model=$(jq -r .model <<<"$plan")
111
+ echo "session model: $model ($(jq -r .source <<<"$plan"))"
112
+ key_env=$(jq -r '.key_env // empty' <<<"$plan")
113
+ if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
114
+ unset SHEPHERD_API_KEY
115
+ # An unset secret arrives as "": a blank key would hide the provider's other credentials.
116
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
117
+ OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
118
+ opencode run --auto -m "$model" --title "shepherd audit" "Run a security audit of this repository (the current directory, its default branch).
119
+ For each play name in: $PLAYS
120
+ follow the play at $RUNNER_TEMP/playbook/plugins/*/plays/<name>.md, reading the templates and data it points at
121
+ under the same plugin directory. Where a play asks for a scanner that is not installed, use what is available and
122
+ say which steps you could not run. Never install global tools, push, open issues or call any URL beyond package
123
+ advisory databases and GitHub's API for this repository.
124
+ Write one Markdown report to $RUNNER_TEMP/audit/report.md: a summary table (play, findings by severity, steps not run),
125
+ then each finding with severity, CWE, file:line and the fix. Never write a secret's value: name its type, file and
126
+ line, and the first 4 characters at most. Nobody is watching this session: never wait for an answer."
127
+ test -s "$RUNNER_TEMP/audit/report.md" || { echo "::error::the audit wrote no report"; exit 1; }
128
+ - name: Withhold a report that carries a credential
129
+ shell: bash
130
+ run: |
131
+ # Before any upload: a credential shape means the redaction failed. Name the kind, never the match.
132
+ found=""
133
+ while IFS='=' read -r kind re; do
134
+ grep -Eq -- "$re" "$RUNNER_TEMP/audit/report.md" && found="$found $kind"
135
+ done <<'PATTERNS'
136
+ aws-key=AKIA[0-9A-Z]{16}
137
+ github-token=gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{40,}
138
+ api-key=sk-[A-Za-z0-9_-]{20,}
139
+ slack-token=xox[abprs]-[A-Za-z0-9-]{10,}
140
+ private-key=-----BEGIN [A-Z ]*PRIVATE KEY
141
+ PATTERNS
142
+ if [ -n "$found" ]; then
143
+ rm -f "$RUNNER_TEMP/audit/report.md"
144
+ echo "::error::the report carried a credential shape ($found ) and was withheld. Rerun the secrets-scan play locally and rotate what it finds."
145
+ exit 1
146
+ fi
147
+ - uses: actions/upload-artifact@v4
148
+ with:
149
+ name: shepherd-audit
150
+ path: ${{ runner.temp }}/audit
151
+ retention-days: 30
152
+
153
+ report:
154
+ needs: [repo, audit]
155
+ runs-on: ubuntu-latest
156
+ permissions:
157
+ issues: write
158
+ steps:
159
+ - uses: actions/download-artifact@v4
160
+ with:
161
+ name: shepherd-audit
162
+ path: audit
163
+ - shell: bash # -eo pipefail
164
+ env:
165
+ GH_TOKEN: ${{ github.token }}
166
+ REPO: ${{ github.repository }}
167
+ PRIVATE: ${{ needs.repo.outputs.private }}
168
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
169
+ run: |
170
+ if [ "$PRIVATE" != "true" ]; then
171
+ echo "Public repository (AUDIT_PUBLIC): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
172
+ exit 0
173
+ fi
174
+ body=$(printf '> 🤖 Automated comment by **Shepherd audit**, not written by a human\n\nRun: %s\n\n%s' "$RUN_URL" "$(head -c 60000 audit/report.md)")
175
+ gh label create shepherd-audit --repo "$REPO" --color B60205 --description "shepherd's scheduled security audit" 2>/dev/null || true
176
+ issue=$(gh issue list --repo "$REPO" --label shepherd-audit --state open --json number --jq '.[0].number // empty')
177
+ if [ -n "$issue" ]; then gh issue comment "$issue" --repo "$REPO" --body "$body"
178
+ else gh issue create --repo "$REPO" --label shepherd-audit --title "Security audit" --body "$body"; fi
@@ -0,0 +1,180 @@
1
+ # shepherd incident in CI: a red run on main, or an error sent in by hand or by an alerting tool, becomes an
2
+ # incident issue, a reproducing test and a fix PR. The PR then goes through CI, stamp and the shepherd
3
+ # workflow like any other. Installed by `shepherd workflows`.
4
+ #
5
+ # Triggers:
6
+ # CI fails on a push to the default branch -> the run URL is the signal
7
+ # workflow_dispatch with `error` -> paste an error or stack trace
8
+ # repository_dispatch type `incident`, payload.error -> an alerting tool (Sentry, Grafana, PagerDuty, a script):
9
+ # gh api repos/<owner>/<repo>/dispatches -f event_type=incident -F 'client_payload[error]=<error text>'
10
+ # Edit `workflows: [ci]` to name your CI workflow. workflow_run runs this file from the default branch only.
11
+ #
12
+ # The signal is untrusted text (alert payloads carry user input), so the agent's job can read the repo and
13
+ # file issues, nothing more: no contents write, no credential in its checkout. It hands its commit over as a
14
+ # git bundle; the `open` job, which runs no model, pushes only an `incident/<n>` branch that builds on the
15
+ # default branch and changes nothing outside INCIDENT_PATHS (no workflows, manifests, lockfiles or config:
16
+ # CI on the PR installs and runs them), then opens the PR. The agent still holds the model key.
17
+ #
18
+ # Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and stamp;
19
+ # with github.token the PR opens but no workflow runs on it. SHEPHERD_API_KEY (or the provider's own key) for the model.
20
+ # Variables: SHEPHERD_MODEL (a model or tier; empty = the team's models.loop or top rung), AWS_REGION (Bedrock),
21
+ # INCIDENT_PATHS (extended regex; empty = ^src/).
22
+ name: shepherd-incident
23
+ on:
24
+ workflow_run:
25
+ workflows: [ci]
26
+ types: [completed]
27
+ workflow_dispatch:
28
+ inputs:
29
+ error:
30
+ description: Error, stack trace or alert text
31
+ required: true
32
+ repository_dispatch:
33
+ types: [incident]
34
+
35
+ permissions: {}
36
+
37
+ jobs:
38
+ investigate:
39
+ if: >-
40
+ (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'failure'
41
+ && github.event.workflow_run.event == 'push'
42
+ && github.event.workflow_run.head_branch == github.event.repository.default_branch)
43
+ || github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
44
+ runs-on: ubuntu-latest
45
+ timeout-minutes: 45
46
+ # On the job, not the workflow: every green CI run starts this workflow and skips, and a workflow-level group
47
+ # would hand that skip the one pending slot a real incident needs. One at a time, so a repeat signal dedupes.
48
+ concurrency:
49
+ group: shepherd-incident
50
+ cancel-in-progress: false
51
+ permissions:
52
+ contents: read
53
+ issues: write
54
+ actions: read
55
+ env:
56
+ SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
57
+ steps:
58
+ - uses: actions/checkout@v4
59
+ with:
60
+ ref: ${{ github.event.repository.default_branch }}
61
+ fetch-depth: 0
62
+ persist-credentials: false
63
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the model key
64
+ # Install your project's dependencies here so the reproducing test can run, with install scripts off and no
65
+ # dependency cache (npm ci --ignore-scripts; setup-node without `cache:`): this job runs the model.
66
+ - shell: bash # -eo pipefail: a failed download fails here, not three steps later
67
+ run: |
68
+ # The pinned CLI on PATH: the skills call `shepherd`, and fall back to an unpinned bunx without it.
69
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
70
+ export PATH="$HOME/.bun/bin:$PATH" && echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
71
+ [ "$(command -v shepherd)" = "$HOME/.bun/bin/shepherd" ] || { echo "shepherd is not the pinned CLI"; exit 1; }
72
+ shepherd install
73
+ curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.0 # 1.x: this installer refuses 2.x
74
+ "$HOME/.opencode/bin/opencode" --version # fails the step if the install did not land
75
+ echo "$HOME/.opencode/bin" >> "$GITHUB_PATH"
76
+ git config user.name "github-actions[bot]"
77
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
78
+ mkdir -p "$RUNNER_TEMP/handoff"
79
+ - name: Write the signal
80
+ env: # through env, never ${{ }} in the script: the error text is untrusted
81
+ RUN_URL: ${{ github.event.workflow_run.html_url }}
82
+ INPUT_ERROR: ${{ github.event.inputs.error }}
83
+ PAYLOAD_ERROR: ${{ github.event.client_payload.error }}
84
+ run: |
85
+ if [ -n "$RUN_URL" ]; then echo "$RUN_URL" > "$RUNNER_TEMP/signal.txt"
86
+ else printf '%s\n' "${INPUT_ERROR:-$PAYLOAD_ERROR}" > "$RUNNER_TEMP/signal.txt"; fi
87
+ - name: Incident
88
+ timeout-minutes: 20 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
89
+ env:
90
+ GH_TOKEN: ${{ github.token }}
91
+ SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
92
+ OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
93
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
94
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
95
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
96
+ DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
97
+ GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
98
+ MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
99
+ GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
100
+ XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
101
+ AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
102
+ AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
103
+ SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
104
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
105
+ OPENCODE_DISABLE_PROJECT_CONFIG: "1"
106
+ OPENCODE_DISABLE_AUTOUPDATE: "1"
107
+ HANDOFF: ${{ runner.temp }}/handoff
108
+ run: |
109
+ # The team's models, from the default branch: the session model, the variable its key goes in, and the
110
+ # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
111
+ plan=$(shepherd ci-models)
112
+ model=$(jq -r .model <<<"$plan")
113
+ echo "session model: $model ($(jq -r .source <<<"$plan"))"
114
+ key_env=$(jq -r '.key_env // empty' <<<"$plan")
115
+ if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
116
+ unset SHEPHERD_API_KEY
117
+ # An unset secret arrives as "": a blank key would hide the provider's other credentials.
118
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
119
+ OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
120
+ opencode run --auto -m "$model" --title "incident" "Load the incident skill and run it on the signal in $RUNNER_TEMP/signal.txt
121
+ (a run URL, or an error or alert text).
122
+ You are running in GitHub Actions on the default branch, already checked out, with no push access.
123
+ At Step 6 do not push or open the PR: commit on incident/<issue>, write the PR title to $HANDOFF/pr-title.txt
124
+ and the body to $HANDOFF/pr-body.md; the next job pushes and opens it.
125
+ Nobody is watching this session: never wait for an answer. Anything you would ask is reported in the final JSON."
126
+ - name: Bundle the fix branch
127
+ env:
128
+ DEFAULT: ${{ github.event.repository.default_branch }}
129
+ run: |
130
+ branch=$(git branch --list 'incident/*' --format='%(refname:short)' | head -1)
131
+ [ -n "$branch" ] || { echo "no fix branch: see the incident issue"; exit 0; }
132
+ echo "$branch" > "$RUNNER_TEMP/handoff/branch"
133
+ git bundle create "$RUNNER_TEMP/handoff/fix.bundle" "origin/$DEFAULT..$branch"
134
+ - uses: actions/upload-artifact@v4
135
+ with:
136
+ name: incident-handoff
137
+ path: ${{ runner.temp }}/handoff
138
+ if-no-files-found: ignore
139
+
140
+ open:
141
+ needs: investigate
142
+ runs-on: ubuntu-latest
143
+ env:
144
+ INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS || '^src/' }} # extended regex every changed path must match
145
+ permissions:
146
+ contents: write
147
+ pull-requests: write
148
+ steps:
149
+ - uses: actions/download-artifact@v4
150
+ id: handoff
151
+ continue-on-error: true # no artifact: no fix branch
152
+ with:
153
+ name: incident-handoff
154
+ path: handoff
155
+ - if: steps.handoff.outcome == 'success' && hashFiles('handoff/fix.bundle') != ''
156
+ uses: actions/checkout@v4
157
+ with:
158
+ ref: ${{ github.event.repository.default_branch }}
159
+ fetch-depth: 0
160
+ path: repo
161
+ token: ${{ secrets.SHEPHERD_TOKEN || github.token }}
162
+ - if: steps.handoff.outcome == 'success' && hashFiles('handoff/fix.bundle') != ''
163
+ working-directory: repo
164
+ shell: bash # -eo pipefail
165
+ env:
166
+ GH_TOKEN: ${{ secrets.SHEPHERD_TOKEN || github.token }}
167
+ DEFAULT: ${{ github.event.repository.default_branch }}
168
+ run: |
169
+ branch=$(cat ../handoff/branch)
170
+ [[ "$branch" =~ ^incident/[0-9]+$ ]] || { echo "::error::unexpected branch name"; exit 1; }
171
+ git fetch -q ../handoff/fix.bundle "$branch:$branch"
172
+ git merge-base "origin/$DEFAULT" "$branch" >/dev/null || { echo "::error::$branch shares no history with $DEFAULT"; exit 1; } # behind is fine: ci-repair updates it
173
+ # NUL-delimited and rename-free: a quoted or renamed path cannot slip past the match. The diff runs on
174
+ # its own so a failure stops here instead of passing an empty list; an empty change is refused too.
175
+ git diff -z --no-renames --name-only "origin/$DEFAULT...$branch" > ../changed
176
+ [ -s ../changed ] || { echo "::error::$branch changes nothing"; exit 1; }
177
+ outside=$(tr '\0' '\n' < ../changed | grep -Ev -- "$INCIDENT_PATHS" || [ $? -eq 1 ])
178
+ [ -z "$outside" ] || { echo "::error::the fix changes paths outside $INCIDENT_PATHS; a person should look:"; echo "$outside"; exit 1; }
179
+ git push origin "$branch:refs/heads/$branch"
180
+ gh pr create --base "$DEFAULT" --head "$branch" --title "$(head -c 200 ../handoff/pr-title.txt)" --body-file ../handoff/pr-body.md