@jagreehal/shepherd 0.14.0 → 0.16.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 +13 -5
- package/README.md +40 -27
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/gate/.shepherd/gate.schema.json +647 -0
- package/gate/.shepherd/gate.yml +122 -0
- package/gate/.shepherd/review-guidance.md +95 -0
- package/gate/src/actions.ts +32 -0
- package/gate/src/cli.ts +1028 -0
- package/gate/src/config.ts +102 -0
- package/gate/src/delta.ts +29 -0
- package/gate/src/env.ts +30 -0
- package/gate/src/eval.ts +288 -0
- package/gate/src/familiarity.ts +461 -0
- package/gate/src/github.ts +761 -0
- package/gate/src/inline.ts +59 -0
- package/gate/src/isolated-cli.ts +281 -0
- package/gate/src/leads.ts +257 -0
- package/gate/src/llm.ts +606 -0
- package/gate/src/notify.ts +57 -0
- package/gate/src/policy.ts +1297 -0
- package/gate/src/provider-errors.ts +80 -0
- package/gate/src/retention.ts +86 -0
- package/gate/src/reviewer.ts +739 -0
- package/gate/src/signals.ts +105 -0
- package/gate/src/smoke-live.ts +64 -0
- package/gate/src/stack.ts +87 -0
- package/gate/src/stories.ts +297 -0
- package/gate/templates/policy-strict.yml +127 -0
- package/gate/templates/reviewer.Dockerfile +8 -0
- package/gate/templates/rules/observability/SKILL.md +33 -0
- package/gate/templates/shepherd-gate-actions.yml +35 -0
- package/gate/templates/shepherd-gate-edited.yml +29 -0
- package/gate/templates/shepherd-gate.yml +111 -0
- package/lenses/dotnet/SKILL.md +1 -1
- package/lenses/go/SKILL.md +1 -1
- package/lenses/java/SKILL.md +1 -1
- package/lenses/nextjs/SKILL.md +1 -1
- package/lenses/node-api/SKILL.md +1 -1
- package/lenses/nx-monorepo/SKILL.md +1 -1
- package/lenses/observability/SKILL.md +1 -1
- package/lenses/owasp-asvs/SKILL.md +1 -1
- package/lenses/owasp-llm/SKILL.md +1 -1
- package/lenses/pstack/SKILL.md +1 -1
- package/lenses/python/SKILL.md +1 -1
- package/lenses/react/SKILL.md +1 -1
- package/lenses/rust/SKILL.md +1 -1
- package/package.json +20 -6
- package/schema/config.json +1 -1
- package/skills/branch-review/SKILL.md +123 -0
- package/skills/ci-repair/SKILL.md +79 -35
- package/skills/garden/SKILL.md +29 -10
- package/skills/garden/references/telemetry.md +4 -4
- package/skills/incident/SKILL.md +19 -9
- package/skills/lens-import/SKILL.md +7 -7
- package/skills/review-maintainability/SKILL.md +1 -1
- package/skills/review-slop/SKILL.md +1 -1
- package/skills/shepherd/SKILL.md +59 -44
- package/skills/shepherd/references/degradation.md +3 -3
- package/skills/shepherd/references/dispatch.md +2 -2
- package/skills/shepherd/references/formats.md +5 -5
- package/skills/shepherd/references/models.md +2 -2
- package/skills/shepherd/references/policy.md +9 -9
- package/skills/swarm/SKILL.md +26 -17
- package/skills/swarm/references/custom-lenses.md +2 -2
- package/skills/swarm/references/formats.md +1 -1
- package/skills/triage/SKILL.md +11 -11
- package/src/bin.ts +10 -0
- package/src/cli.ts +283 -41
- package/src/config.ts +26 -25
- package/src/doctor.ts +31 -18
- package/src/garden-traces.ts +13 -13
- package/src/garden.ts +43 -8
- package/src/lens.ts +19 -7
- package/src/setup.ts +72 -0
- package/src/stack.ts +2 -2
- package/src/status.ts +80 -0
- package/src/summary.ts +52 -9
- package/src/trace.ts +4 -4
- package/src/working.ts +30 -0
- package/templates/shepherd-audit.yml +7 -15
- package/templates/shepherd-incident.yml +9 -12
- package/templates/shepherd.yml +39 -40
package/src/summary.ts
CHANGED
|
@@ -91,7 +91,7 @@ const Finding = z.object({
|
|
|
91
91
|
// has no line on the new side.
|
|
92
92
|
side: z.enum(["LEFT", "RIGHT"]).nullish().catch(undefined).transform((v) => v ?? "RIGHT"),
|
|
93
93
|
severity: Severity,
|
|
94
|
-
lens: z.string(),
|
|
94
|
+
lens: z.string().transform((l) => l.replace(/^convergent:\s*/i, "")), // the tag's own "convergent:" prefix: the render adds it once
|
|
95
95
|
body: z.string(),
|
|
96
96
|
convergent: flag(false),
|
|
97
97
|
// A reader triages by the title alone: a claim they can check, such as "`firstName` returns the second word".
|
|
@@ -255,7 +255,43 @@ const fromChecks = (f: { lens: string }) => f.lens.startsWith("checks/");
|
|
|
255
255
|
/** Text a model escaped twice: two or more literal `\\n` and no real line break. One may be code the body quotes. */
|
|
256
256
|
const unescaped = (t: string) => (!t.includes("\n") && t.split("\\n").length > 2 ? t.replaceAll("\\n", "\n").replaceAll("\\t", "\t").replaceAll('\\"', '"') : t);
|
|
257
257
|
|
|
258
|
-
|
|
258
|
+
/** An unresolved review thread shepherd opened: its URL and the ids of the findings its first comment carries. */
|
|
259
|
+
export type OpenThread = { url: string; ids: string[] };
|
|
260
|
+
|
|
261
|
+
/** A finding's id: its place, lens and title. A later round's identical finding has the same id; a reworded one does not. */
|
|
262
|
+
export const findingId = (f: { file?: string; side?: string; line?: number | string; lens: string; title?: string }) =>
|
|
263
|
+
createHash("sha256").update(`${f.file ?? ""}:${f.side ?? "RIGHT"}:${f.line ?? ""}:${f.lens}:${f.title ?? ""}`).digest("hex").slice(0, 12);
|
|
264
|
+
|
|
265
|
+
const FINDING_IDS = /<!-- shepherd-finding:([0-9a-f ]+) -->/;
|
|
266
|
+
|
|
267
|
+
export type ThreadNode = { isResolved: boolean; comments: { nodes: { url: string; body: string; author: { login: string; __typename: string } | null }[] } };
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* The PR's open swarm threads. One counts only when shepherd's own account opened it: GitHub Actions' bot in CI, or
|
|
271
|
+
* `viewer`, the signed-in operator whose account local runs post through. The header alone proves nothing: anyone
|
|
272
|
+
* can paste it.
|
|
273
|
+
*/
|
|
274
|
+
export function swarmThreads(nodes: readonly ThreadNode[], viewer: string | null): OpenThread[] {
|
|
275
|
+
const ours = (a: ThreadNode["comments"]["nodes"][number]["author"]) => a !== null && ((a.__typename === "Bot" && a.login === "github-actions") || a.login === viewer);
|
|
276
|
+
|
|
277
|
+
return nodes.flatMap((t) => {
|
|
278
|
+
const first = t.comments.nodes[0];
|
|
279
|
+
|
|
280
|
+
return !t.isResolved && first && ours(first.author) && /🤖 Automated comment by .*swarm\*\*/.test(first.body) ? [{ url: first.url, ids: FINDING_IDS.exec(first.body)?.[1]?.split(" ") ?? [] }] : [];
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* The open thread that carries this finding, matched explicitly, never by wording: the finding names the thread in its
|
|
286
|
+
* `url` (swarm does for a finding it judged a repeat), or the thread's comment carries this exact finding's id.
|
|
287
|
+
*/
|
|
288
|
+
export function openThreadFor(f: Parameters<typeof findingId>[0] & { url?: string }, open: readonly OpenThread[] = []): OpenThread | undefined {
|
|
289
|
+
const id = findingId(f);
|
|
290
|
+
|
|
291
|
+
return open.find((t) => t.url === f.url || t.ids.includes(id));
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null, open?: readonly OpenThread[]) {
|
|
259
295
|
const s = SummaryInput.parse(raw);
|
|
260
296
|
const real = (url: string | undefined) => (url === undefined || threads === undefined || threads.has(url) ? url : undefined);
|
|
261
297
|
|
|
@@ -288,6 +324,9 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, r
|
|
|
288
324
|
// same lines.
|
|
289
325
|
if (read) for (const f of s.findings) place(f, read);
|
|
290
326
|
|
|
327
|
+
// After placement: a finding's id names the lines its inline comment was posted on, which placement can move.
|
|
328
|
+
for (const f of s.findings) f.url ??= openThreadFor(f, open)?.url;
|
|
329
|
+
|
|
291
330
|
return s;
|
|
292
331
|
}
|
|
293
332
|
|
|
@@ -469,8 +508,8 @@ export function reviewedTips(previous: string): { head_sha: string; base_sha: st
|
|
|
469
508
|
* The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
|
|
470
509
|
* it is the body alone, for the handoff file the publish job wraps in its own marker and header.
|
|
471
510
|
*/
|
|
472
|
-
export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string>, read?: (path: string) => string | null): string {
|
|
473
|
-
const s = checkedRound(raw, threads, read);
|
|
511
|
+
export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string>, read?: (path: string) => string | null, open?: readonly OpenThread[]): string {
|
|
512
|
+
const s = checkedRound(raw, threads, read, open);
|
|
474
513
|
// A lens fanout listed for this head that the round does not report never ran as its own reviewer, so it shows
|
|
475
514
|
// as could_not_run.
|
|
476
515
|
const wave = fanout ? Fanout.parse(fanout) : null;
|
|
@@ -543,7 +582,7 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
|
|
|
543
582
|
if (walk.length) out.push(...section("<strong>Walkthrough</strong>", walk.join("\n").trim().split("\n")));
|
|
544
583
|
|
|
545
584
|
// Finishing touches: the commands this repository answers.
|
|
546
|
-
if (findings.length) out.push("✨ Comment `/shepherd` to have shepherd work through these findings, as far as `fixes.mode` allows, or `/
|
|
585
|
+
if (findings.length) out.push("✨ Comment `/shepherd` to have shepherd work through these findings, as far as `fixes.mode` allows, or `/gate` for a fresh verdict.", "");
|
|
547
586
|
|
|
548
587
|
if (s.still_open.length) out.push(...section(`<strong>Still open:</strong> ${s.still_open.length}`, s.still_open.map((t) => (t.url ? `- [${defuse(t.title, true).replace(/[[\]]/g, "")}](${t.url})` : `- ${defuse(t.title, true)}`))));
|
|
549
588
|
|
|
@@ -763,7 +802,9 @@ export function commentableLines(diff: string, side: "LEFT" | "RIGHT" = "RIGHT")
|
|
|
763
802
|
return lines;
|
|
764
803
|
}
|
|
765
804
|
|
|
766
|
-
export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>, commentable?: Map<string, Set<number>>, removable?: Map<string, Set<number
|
|
805
|
+
export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>, commentable?: Map<string, Set<number>>, removable?: Map<string, Set<number>>, open?: readonly OpenThread[]) {
|
|
806
|
+
// A finding an open thread of ours already carries, matched explicitly, posts no second comment.
|
|
807
|
+
const fresh = (f: Parameters<typeof openThreadFor>[0]) => !openThreadFor(f, open);
|
|
767
808
|
const s = checkedRound(raw, threads, read);
|
|
768
809
|
const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
|
|
769
810
|
|
|
@@ -788,7 +829,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
788
829
|
return text === null || end <= text.replace(/\n$/, "").split("\n").length;
|
|
789
830
|
};
|
|
790
831
|
|
|
791
|
-
const anchored = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f)));
|
|
832
|
+
const anchored = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f) && fresh(f)));
|
|
792
833
|
// One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
|
|
793
834
|
// in the summary.
|
|
794
835
|
const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.side}:${f.line}`;
|
|
@@ -812,7 +853,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
812
853
|
"> [!NOTE]",
|
|
813
854
|
header,
|
|
814
855
|
"",
|
|
815
|
-
`**[${defuse(f.lens, true)}]** ${glyph(f.severity)} ${f.severity}`,
|
|
856
|
+
`**[${f.convergent ? "convergent: " : ""}${defuse(f.lens, true)}]** ${glyph(f.severity)} ${f.severity}`,
|
|
816
857
|
...(f.title ? ["", `**${defuse(f.title, true)}**`] : []),
|
|
817
858
|
...reintroduced(f),
|
|
818
859
|
"",
|
|
@@ -837,7 +878,9 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
837
878
|
"</details>",
|
|
838
879
|
].join("\n");
|
|
839
880
|
|
|
840
|
-
|
|
881
|
+
// Every finding this comment carries, by id, so the summary links each to it and a later round knows it.
|
|
882
|
+
const ids = [f, ...anchored.filter((g) => g !== f && at(g) === at(f))].map(findingId).join(" ");
|
|
883
|
+
const comment: InlineComment = { path: f.file, line: end ?? start, side: f.side, body: `${body}\n<!-- shepherd-finding:${ids} -->` };
|
|
841
884
|
|
|
842
885
|
if (end !== undefined && end !== start) {
|
|
843
886
|
comment.start_line = start;
|
package/src/trace.ts
CHANGED
|
@@ -8,8 +8,8 @@ import path from "node:path";
|
|
|
8
8
|
import { z } from "zod";
|
|
9
9
|
import { stateDir } from "./local.ts";
|
|
10
10
|
|
|
11
|
-
// `
|
|
12
|
-
export const STAGES = ["checks", "swarm", "verify", "triage", "simplify", "ci-repair", "
|
|
11
|
+
// `gate` is the wait for gate's verdict.
|
|
12
|
+
export const STAGES = ["checks", "swarm", "verify", "triage", "simplify", "ci-repair", "gate"] as const;
|
|
13
13
|
|
|
14
14
|
const Event = z.object({
|
|
15
15
|
at: z.string(),
|
|
@@ -93,7 +93,7 @@ export function stagesFrom(text: string, now: Date): StageRecord {
|
|
|
93
93
|
return { start: events[0]?.at ?? null, stages: stages.sort((a, b) => a.start.localeCompare(b.start)) };
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
-
/** What ties an iteration to the PR, the CI run and other traces:
|
|
96
|
+
/** What ties an iteration to the PR, the CI run and other traces: gate's review, a CI run's trace. */
|
|
97
97
|
export type Iteration = {
|
|
98
98
|
repo: string;
|
|
99
99
|
pr: number;
|
|
@@ -108,7 +108,7 @@ export type Iteration = {
|
|
|
108
108
|
|
|
109
109
|
const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
|
|
110
110
|
|
|
111
|
-
/** The iteration span's attributes, named like
|
|
111
|
+
/** The iteration span's attributes, named like gate's so one query finds both. An absent value stays undefined. */
|
|
112
112
|
export const iterationAttributes = (it: Iteration, stages: Stage[]) => ({
|
|
113
113
|
"vcs.repository.name": it.repo,
|
|
114
114
|
"vcs.change.id": String(it.pr),
|
package/src/working.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// The "shepherd is reviewing" note: one comment the iteration posts as it starts and the finalizer deletes, so the
|
|
2
|
+
// PR shows work in progress between the push and the summary. It stays apart from the summary comment, whose
|
|
3
|
+
// update-in-place logic it must never confuse.
|
|
4
|
+
|
|
5
|
+
export const WORKING_MARKER = "<!-- shepherd-working -->";
|
|
6
|
+
|
|
7
|
+
/** The animated mascot. A branch URL, so every release shows the same image. */
|
|
8
|
+
export const WORKING_IMAGE = "https://raw.githubusercontent.com/jagreehal/shepherd/main/assets/shepherd-reviewing.svg";
|
|
9
|
+
|
|
10
|
+
/** How the note looks: the repository's branding when it has one (`branding()` output, already escaped). */
|
|
11
|
+
export type WorkingLook = { name: string; header: string; image: string };
|
|
12
|
+
|
|
13
|
+
export const DEFAULT_LOOK: WorkingLook = { name: "shepherd", header: "> 🤖 Automated comment by **Shepherd swarm**, not written by a human", image: WORKING_IMAGE };
|
|
14
|
+
|
|
15
|
+
export function workingNote(head: string, runUrl: string, look: WorkingLook = DEFAULT_LOOK): string {
|
|
16
|
+
return [
|
|
17
|
+
WORKING_MARKER,
|
|
18
|
+
look.header,
|
|
19
|
+
"",
|
|
20
|
+
`<img src="${look.image}" width="96" align="left" alt="">`,
|
|
21
|
+
"",
|
|
22
|
+
`**${look.name} is reviewing \`${head.slice(0, 7)}\`.** The summary replaces this note when the run ends.`,
|
|
23
|
+
"",
|
|
24
|
+
`[Follow the run](${runUrl}) · \`shepherd status\` from a terminal`,
|
|
25
|
+
'<br clear="left">',
|
|
26
|
+
].join("\n");
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The note's comment among the PR's comments: the bot's own, carrying the marker. */
|
|
30
|
+
export const isWorkingNote = (c: { user: { login: string }; body: string }) => c.user.login === "github-actions[bot]" && c.body.startsWith(WORKING_MARKER);
|
|
@@ -6,14 +6,12 @@
|
|
|
6
6
|
# The agent's job reads the repository and writes a report, nothing more: no write credential, no persisted
|
|
7
7
|
# checkout token. A report carrying a credential shape is withheld before anything is uploaded. The report
|
|
8
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
|
|
9
|
+
# repository issues and artifacts are public, so the audit runs there only when ci.audit.public is `true`: the
|
|
10
10
|
# report then becomes a public artifact.
|
|
11
11
|
#
|
|
12
|
-
# Secrets:
|
|
13
|
-
# Variables: SHEPHERD_MODEL (optional
|
|
14
|
-
#
|
|
15
|
-
# AUDIT_PUBLIC (ci.audit.public: `true` to run on a public repository, publishing the report).
|
|
16
|
-
# Each variable overrides its key in .shepherd/config.yml.
|
|
12
|
+
# Secrets: the model key, under the provider's own name.
|
|
13
|
+
# Variables: SHEPHERD_MODEL (optional provider/model, over models.loop), AWS_REGION (Bedrock).
|
|
14
|
+
# Settings: ci.audit.plays and ci.audit.public in .shepherd/config.yml.
|
|
17
15
|
name: shepherd-audit
|
|
18
16
|
on:
|
|
19
17
|
schedule:
|
|
@@ -21,7 +19,7 @@ on:
|
|
|
21
19
|
workflow_dispatch:
|
|
22
20
|
inputs:
|
|
23
21
|
plays:
|
|
24
|
-
description: Plays to run, space-separated (empty = ci.audit.plays,
|
|
22
|
+
description: Plays to run, space-separated (empty = ci.audit.plays, or the default)
|
|
25
23
|
required: false
|
|
26
24
|
|
|
27
25
|
permissions: {}
|
|
@@ -54,8 +52,6 @@ jobs:
|
|
|
54
52
|
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
55
53
|
GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
|
|
56
54
|
AWS_REGION: ${{ vars.AWS_REGION }}
|
|
57
|
-
AUDIT_PLAYS: ${{ vars.AUDIT_PLAYS }}
|
|
58
|
-
AUDIT_PUBLIC: ${{ vars.AUDIT_PUBLIC }}
|
|
59
55
|
run: |
|
|
60
56
|
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
61
57
|
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
|
@@ -112,7 +108,6 @@ jobs:
|
|
|
112
108
|
timeout-minutes: 45 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
|
|
113
109
|
env:
|
|
114
110
|
GH_TOKEN: ${{ github.token }}
|
|
115
|
-
SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
|
|
116
111
|
OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
|
|
117
112
|
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
118
113
|
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
@@ -129,14 +124,11 @@ jobs:
|
|
|
129
124
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md stay out of the agent's config
|
|
130
125
|
OPENCODE_DISABLE_AUTOUPDATE: "1"
|
|
131
126
|
run: |
|
|
132
|
-
# The team's models, from the default branch: the session model
|
|
127
|
+
# The team's models, from the default branch: the session model and the
|
|
133
128
|
# OpenCode agents that carry the ladder and pins, so each runner gets its own model.
|
|
134
129
|
plan=$(shepherd ci-models)
|
|
135
130
|
model=$(jq -r .model <<<"$plan")
|
|
136
131
|
echo "session model: $model ($(jq -r .source <<<"$plan"))"
|
|
137
|
-
key_env=$(jq -r '.key_env // empty' <<<"$plan")
|
|
138
|
-
if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
|
|
139
|
-
unset SHEPHERD_API_KEY
|
|
140
132
|
# Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
|
|
141
133
|
# provider's other credentials.
|
|
142
134
|
keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
|
|
@@ -197,7 +189,7 @@ jobs:
|
|
|
197
189
|
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
198
190
|
run: |
|
|
199
191
|
if [ "$PRIVATE" != "true" ]; then
|
|
200
|
-
echo "Public repository (
|
|
192
|
+
echo "Public repository (ci.audit.public): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
|
|
201
193
|
exit 0
|
|
202
194
|
fi
|
|
203
195
|
# The header came out of a job a model ran in: one line with the automated prefix, or the default.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
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,
|
|
2
|
+
# incident issue, a reproducing test and a fix PR. The PR then goes through CI, gate and the shepherd
|
|
3
3
|
# workflow like any other. Installed by `shepherd workflows`.
|
|
4
4
|
#
|
|
5
5
|
# Triggers:
|
|
@@ -12,13 +12,13 @@
|
|
|
12
12
|
# The signal is untrusted text (alert payloads carry user input), so the agent's job can read the repo and
|
|
13
13
|
# file issues, nothing more: no contents write, no credential in its checkout. It hands its commit over as a
|
|
14
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
|
|
15
|
+
# default branch and changes nothing outside ci.incident_paths (no workflows, manifests, lockfiles or config:
|
|
16
16
|
# CI on the PR installs and runs them), then opens the PR. The agent still holds the model key.
|
|
17
17
|
#
|
|
18
|
-
# Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and
|
|
19
|
-
# with github.token the PR opens but no workflow runs on it.
|
|
20
|
-
# Variables: SHEPHERD_MODEL (optional
|
|
21
|
-
#
|
|
18
|
+
# Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and gate;
|
|
19
|
+
# with github.token the PR opens but no workflow runs on it. the model key, under the provider's own name.
|
|
20
|
+
# Variables: SHEPHERD_MODEL (optional provider/model, over models.loop), AWS_REGION (Bedrock).
|
|
21
|
+
# Settings: ci.incident_paths in .shepherd/config.yml (empty = ^src/).
|
|
22
22
|
name: shepherd-incident
|
|
23
23
|
on:
|
|
24
24
|
workflow_run:
|
|
@@ -89,7 +89,6 @@ jobs:
|
|
|
89
89
|
timeout-minutes: 20 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
|
|
90
90
|
env:
|
|
91
91
|
GH_TOKEN: ${{ github.token }}
|
|
92
|
-
SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
|
|
93
92
|
OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
|
|
94
93
|
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
95
94
|
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
@@ -107,15 +106,12 @@ jobs:
|
|
|
107
106
|
OPENCODE_DISABLE_AUTOUPDATE: "1"
|
|
108
107
|
HANDOFF: ${{ runner.temp }}/handoff
|
|
109
108
|
run: |
|
|
110
|
-
# The team's models, from the default branch: the session model
|
|
109
|
+
# The team's models, from the default branch: the session model and the
|
|
111
110
|
# OpenCode agents that carry the ladder and pins, so each runner gets its own model.
|
|
112
111
|
plan=$(shepherd ci-models)
|
|
113
112
|
AWS_REGION=$(shepherd ci-settings | jq -r .aws_region.value) && export AWS_REGION # ci.aws_region, or the variable
|
|
114
113
|
model=$(jq -r .model <<<"$plan")
|
|
115
114
|
echo "session model: $model ($(jq -r .source <<<"$plan"))"
|
|
116
|
-
key_env=$(jq -r '.key_env // empty' <<<"$plan")
|
|
117
|
-
if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
|
|
118
|
-
unset SHEPHERD_API_KEY
|
|
119
115
|
# Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
|
|
120
116
|
# provider's other credentials.
|
|
121
117
|
keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
|
|
@@ -126,11 +122,13 @@ jobs:
|
|
|
126
122
|
You are running in GitHub Actions on the default branch, already checked out, with no push access.
|
|
127
123
|
At Step 6 do not push or open the PR: commit on incident/<issue>, write the PR title to $HANDOFF/pr-title.txt
|
|
128
124
|
and the body to $HANDOFF/pr-body.md; the next job pushes and opens it.
|
|
125
|
+
When the skill stops because a security failure stays private, create the empty file $HANDOFF/private.
|
|
129
126
|
Nobody is watching this session: never wait for an answer. Anything you would ask is reported in the final JSON."
|
|
130
127
|
- name: Bundle the fix branch
|
|
131
128
|
env:
|
|
132
129
|
DEFAULT: ${{ github.event.repository.default_branch }}
|
|
133
130
|
run: |
|
|
131
|
+
[ ! -e "$RUNNER_TEMP/handoff/private" ] || { echo "::error::a possible security failure needs private handling"; exit 1; }
|
|
134
132
|
branch=$(git branch --list 'incident/*' --format='%(refname:short)' | head -1)
|
|
135
133
|
[ -n "$branch" ] || { echo "no fix branch: see the incident issue"; exit 0; }
|
|
136
134
|
echo "$branch" > "$RUNNER_TEMP/handoff/branch"
|
|
@@ -164,7 +162,6 @@ jobs:
|
|
|
164
162
|
env:
|
|
165
163
|
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
166
164
|
GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
|
|
167
|
-
INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS }}
|
|
168
165
|
run: |
|
|
169
166
|
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
170
167
|
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
package/templates/shepherd.yml
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
# shepherd in CI: one loop iteration each time CI or
|
|
2
|
-
# when a PR gets the
|
|
1
|
+
# shepherd in CI: one loop iteration each time CI or gate finishes on a PR, on a `/shepherd` comment,
|
|
2
|
+
# when a PR gets the ci.label label, or from the sweep. Each iteration's fixes are pushed, CI and gate run
|
|
3
3
|
# on the new head, and their completion starts the next one, until shepherd sets a final `shepherd` status
|
|
4
4
|
# (success, or failure naming what the author must do). Installed by `shepherd workflows`.
|
|
5
5
|
#
|
|
@@ -12,36 +12,29 @@
|
|
|
12
12
|
# Secrets:
|
|
13
13
|
# SHEPHERD_TOKEN fine-grained PAT: contents, pull requests and commit statuses (read/write). Only
|
|
14
14
|
# `gate` and `publish` see it. Pushes made with github.token start no workflows, so the loop would stall.
|
|
15
|
-
#
|
|
16
|
-
# Store
|
|
17
|
-
# only `iterate` reads
|
|
18
|
-
# Or each provider's own secret (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
|
|
19
|
-
# DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...) when the ladder mixes providers.
|
|
15
|
+
# the model key, under the provider's own name (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY,
|
|
16
|
+
# OPENROUTER_API_KEY, DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...). Store it as an environment's
|
|
17
|
+
# secret (`shepherd workflows --environment <name>`) so only `iterate` reads it.
|
|
20
18
|
# SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
|
|
21
19
|
# you, is ready to merge, or the iteration stopped on an error.
|
|
22
|
-
# Settings
|
|
23
|
-
# push_deny),
|
|
24
|
-
# its source. Each repository variable below is an optional override: when set, it wins over the config.
|
|
20
|
+
# Settings live in .shepherd/config.yml (models.loop, and ci: label, aws_region, notify_on, max_commits,
|
|
21
|
+
# push_deny), reviewed and read from the default branch; `shepherd config explain` lists each with its source.
|
|
25
22
|
# Variables:
|
|
26
|
-
# SHEPHERD_MODEL optional
|
|
27
|
-
#
|
|
28
|
-
#
|
|
29
|
-
# their own models from the team's tiers, ladder and pins (shepherd models shows them).
|
|
30
|
-
# AWS_REGION ci.aws_region: the Bedrock region, for a bedrock: model.
|
|
31
|
-
# SHEPHERD_LABEL ci.label: shepherd only PRs carrying this label. Whatever opens PRs (a person, Claude
|
|
32
|
-
# Code, Codex, another agent) hands one over by adding it.
|
|
33
|
-
# SHEPHERD_NOTIFY_ON ci.notify_on: states that notify, e.g. "failure"; empty = success,failure,error.
|
|
34
|
-
# SHEPHERD_MAX_COMMITS ci.max_commits: shepherd commits on one PR before it stops for a person; empty = 20.
|
|
23
|
+
# SHEPHERD_MODEL optional: provider/model for this repository (e.g. opencode-go/deepseek-v4.1-flash,
|
|
24
|
+
# anthropic/claude-sonnet-5.5, amazon-bedrock/eu.amazon.nova-pro-v1:0), over models.loop.
|
|
25
|
+
# AWS_REGION the Bedrock region, for a Bedrock model.
|
|
35
26
|
# SHEPHERD_PUSH_DENY replaces the built-in deny list (an admin's escape hatch). ci.push_deny in config can only
|
|
36
27
|
# ADD patterns to whichever list applies. Extended regex of paths a handed-off fix may not touch; empty = workflows,
|
|
37
28
|
# git and editor hooks, package manager config, manifests and lockfiles.
|
|
38
29
|
#
|
|
39
|
-
# Edit `workflows: [ci,
|
|
30
|
+
# Edit `workflows: [ci, shepherd-gate]` to name your CI workflow. workflow_run, pull_request_target and schedule
|
|
40
31
|
# run this file from the default branch, so a PR cannot change how it is shepherded.
|
|
41
32
|
name: shepherd
|
|
33
|
+
# The PR in each run's title, so `shepherd review <pr>` finds its run among other PRs'.
|
|
34
|
+
run-name: shepherd ${{ github.event.workflow_run.pull_requests[0].number || github.event.issue.number || github.event.pull_request.number || inputs.pr || github.event_name }}
|
|
42
35
|
on:
|
|
43
36
|
workflow_run:
|
|
44
|
-
workflows: [ci,
|
|
37
|
+
workflows: [ci, shepherd-gate]
|
|
45
38
|
types: [completed]
|
|
46
39
|
issue_comment:
|
|
47
40
|
types: [created]
|
|
@@ -100,10 +93,7 @@ jobs:
|
|
|
100
93
|
id: settings
|
|
101
94
|
env:
|
|
102
95
|
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
103
|
-
SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
|
|
104
96
|
AWS_REGION: ${{ vars.AWS_REGION }}
|
|
105
|
-
SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
|
|
106
|
-
SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
|
|
107
97
|
run: |
|
|
108
98
|
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
109
99
|
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
|
@@ -133,8 +123,7 @@ jobs:
|
|
|
133
123
|
&& github.event.workflow_run.head_repository.full_name == github.repository)
|
|
134
124
|
|| (github.event_name == 'issue_comment' && github.event.issue.pull_request != null
|
|
135
125
|
&& startsWith(github.event.comment.body, '/shepherd'))
|
|
136
|
-
||
|
|
137
|
-
&& (vars.SHEPHERD_LABEL == '' || github.event.label.name == vars.SHEPHERD_LABEL))
|
|
126
|
+
|| github.event_name == 'pull_request_target'
|
|
138
127
|
|| github.event_name == 'workflow_dispatch'
|
|
139
128
|
runs-on: ubuntu-latest
|
|
140
129
|
timeout-minutes: 5
|
|
@@ -170,10 +159,7 @@ jobs:
|
|
|
170
159
|
env:
|
|
171
160
|
GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
|
|
172
161
|
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
173
|
-
SHEPHERD_LABEL: ${{ vars.SHEPHERD_LABEL }}
|
|
174
162
|
AWS_REGION: ${{ vars.AWS_REGION }}
|
|
175
|
-
SHEPHERD_NOTIFY_ON: ${{ vars.SHEPHERD_NOTIFY_ON }}
|
|
176
|
-
SHEPHERD_MAX_COMMITS: ${{ vars.SHEPHERD_MAX_COMMITS }}
|
|
177
163
|
run: |
|
|
178
164
|
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
179
165
|
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
|
@@ -295,6 +281,13 @@ jobs:
|
|
|
295
281
|
git config user.name "$GIT_NAME"
|
|
296
282
|
git config user.email "$GIT_EMAIL"
|
|
297
283
|
mkdir -p "$RUNNER_TEMP/handoff"
|
|
284
|
+
# A note on the PR while the model works; the finalizer deletes it. Cosmetic, so it never fails the job.
|
|
285
|
+
- name: Show that shepherd is reviewing
|
|
286
|
+
continue-on-error: true
|
|
287
|
+
env:
|
|
288
|
+
GH_TOKEN: ${{ github.token }}
|
|
289
|
+
H0: ${{ needs.gate.outputs.head }}
|
|
290
|
+
run: shepherd working --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$H0"
|
|
298
291
|
- name: One shepherd iteration
|
|
299
292
|
timeout-minutes: 30 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
|
|
300
293
|
env:
|
|
@@ -302,7 +295,6 @@ jobs:
|
|
|
302
295
|
SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
|
|
303
296
|
SHEPHERD_FANOUT: ${{ runner.temp }}/fanout.json
|
|
304
297
|
BASE: ${{ needs.gate.outputs.base }}
|
|
305
|
-
SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
|
|
306
298
|
OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
|
|
307
299
|
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
308
300
|
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
@@ -319,14 +311,11 @@ jobs:
|
|
|
319
311
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
|
|
320
312
|
OPENCODE_DISABLE_AUTOUPDATE: "1"
|
|
321
313
|
run: |
|
|
322
|
-
# The team's models, from the default branch: the session model
|
|
314
|
+
# The team's models, from the default branch: the session model and the
|
|
323
315
|
# OpenCode agents that carry the ladder and pins, so each runner gets its own model.
|
|
324
316
|
plan=$(shepherd ci-models)
|
|
325
317
|
model=$(jq -r .model <<<"$plan")
|
|
326
318
|
echo "session model: $model ($(jq -r .source <<<"$plan"))"
|
|
327
|
-
key_env=$(jq -r '.key_env // empty' <<<"$plan")
|
|
328
|
-
if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
|
|
329
|
-
unset SHEPHERD_API_KEY
|
|
330
319
|
# Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
|
|
331
320
|
# provider's other credentials.
|
|
332
321
|
keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
|
|
@@ -347,7 +336,7 @@ jobs:
|
|
|
347
336
|
yourself. You are running in GitHub Actions on the PR branch,
|
|
348
337
|
already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
|
|
349
338
|
would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
|
|
350
|
-
iterations; the next one starts when CI or
|
|
339
|
+
iterations; the next one starts when CI or gate finishes on the head the workflow pushes."
|
|
351
340
|
# The job checks the round itself. A round that does not render gets one short call with the exact errors.
|
|
352
341
|
round="$SHEPHERD_HANDOFF/round.json"
|
|
353
342
|
if [ -f "$round" ] && ! errors=$(shepherd summary "$round" --body 2>&1 >/dev/null); then
|
|
@@ -482,7 +471,7 @@ jobs:
|
|
|
482
471
|
elif state == "pending":
|
|
483
472
|
# Nothing pushed and no CI re-run asked for: findings above NIT leave work for the author, so the status
|
|
484
473
|
# is failure and the sweep, which re-runs pending PRs every half hour, leaves the PR to them. Otherwise it
|
|
485
|
-
# stays pending: success needs
|
|
474
|
+
# stays pending: success needs gate's approval, green CI and no open thread, which this step cannot see.
|
|
486
475
|
try:
|
|
487
476
|
reruns = open("handoff/rerun-jobs.txt").read().strip() not in ("", "[]")
|
|
488
477
|
except OSError:
|
|
@@ -507,7 +496,7 @@ jobs:
|
|
|
507
496
|
echo "state=$state" >> "$GITHUB_OUTPUT"
|
|
508
497
|
# Under suggest, posting is the review. If the iteration ended without its summary on the PR, post the findings it
|
|
509
498
|
# handed off. findings.md is model output: capped, its markers and HTML comments escaped (it must not pass for a
|
|
510
|
-
#
|
|
499
|
+
# gate or shepherd comment), mentions and images defused, and built into the body in Python, never by the shell.
|
|
511
500
|
# The renderers, when the iteration handed off its round: the summary and inline review are then built in code.
|
|
512
501
|
- if: env.ITERATED == 'success' && steps.push.outputs.stale != 'true' && hashFiles('handoff/round.json') != ''
|
|
513
502
|
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0: pinned, this job holds the write token
|
|
@@ -550,16 +539,18 @@ jobs:
|
|
|
550
539
|
fi
|
|
551
540
|
fi
|
|
552
541
|
fanout=(); [ -f handoff/fanout.json ] && fanout=(--fanout ../handoff/fanout.json)
|
|
542
|
+
# The CLI's render is code, not model output: it posts as rendered, keeping the reviewed-head marker the next
|
|
543
|
+
# round's interdiff reads, and links each finding to its thread (rendered after the inline review posts).
|
|
553
544
|
# A round the CLI cannot render keeps whatever findings.md the model wrote; with neither, say so and stop.
|
|
554
|
-
if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md
|
|
555
|
-
|
|
545
|
+
if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md "${fanout[@]}") > findings.out; then
|
|
546
|
+
rendered=1
|
|
556
547
|
elif [ ! -f handoff/findings.md ]; then
|
|
557
548
|
echo "::warning::could not render the round's summary, and the iteration left no findings.md"; exit 0
|
|
558
549
|
fi
|
|
559
550
|
else
|
|
560
551
|
[ -n "$fresh" ] && grep -q "@ ${H0:0:7}" summary.md && { echo "the iteration posted its summary ($id)"; exit 0; }
|
|
561
552
|
fi
|
|
562
|
-
python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
|
|
553
|
+
[ -n "${rendered:-}" ] || python3 - handoff/findings.md summary.md "${H0:0:7}" > findings.out <<'PY'
|
|
563
554
|
import re, sys
|
|
564
555
|
CAP = 60000
|
|
565
556
|
def defuse(text):
|
|
@@ -613,6 +604,14 @@ jobs:
|
|
|
613
604
|
SHEPHERD_NOTIFY_WEBHOOK: ${{ secrets.SHEPHERD_NOTIFY_WEBHOOK }}
|
|
614
605
|
SHEPHERD_NOTIFY_ON: ${{ needs.gate.outputs.notify_on }} # ci.notify_on or the variable
|
|
615
606
|
run: shepherd notify --pr "$PR" --repo "$GITHUB_REPOSITORY" --head "$HEAD_SHA" --state "$STATE" --file description.txt
|
|
607
|
+
- name: Remove the reviewing note
|
|
608
|
+
if: always()
|
|
609
|
+
continue-on-error: true
|
|
610
|
+
env:
|
|
611
|
+
GH_TOKEN: ${{ github.token }}
|
|
612
|
+
run: |
|
|
613
|
+
gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" --paginate --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("<!-- shepherd-working -->"))) | .id' |
|
|
614
|
+
while read -r id; do gh api -X DELETE "repos/$GITHUB_REPOSITORY/issues/comments/$id" >/dev/null; done
|
|
616
615
|
# Any step above failing (checkout, push, status) must not leave the gate's pending for the sweep to rerun.
|
|
617
616
|
- name: Report a failed publish
|
|
618
617
|
if: always() && failure()
|