@jagreehal/shepherd 0.4.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.
- package/README.md +1 -0
- package/THIRD_PARTY_NOTICES.md +11 -0
- package/lenses/dotnet/SKILL.md +32 -0
- package/lenses/go/SKILL.md +30 -0
- package/lenses/java/SKILL.md +31 -0
- package/lenses/nextjs/SKILL.md +33 -0
- package/lenses/node-api/SKILL.md +32 -0
- package/lenses/nx-monorepo/SKILL.md +30 -0
- package/lenses/owasp-asvs/SKILL.md +50 -0
- package/lenses/owasp-llm/SKILL.md +44 -0
- package/lenses/python/SKILL.md +32 -0
- package/lenses/react/SKILL.md +33 -0
- package/lenses/rust/SKILL.md +31 -0
- package/package.json +2 -1
- package/packs/dotnet.yml +6 -0
- package/packs/go.yml +6 -0
- package/packs/java.yml +6 -0
- package/packs/nextjs.yml +7 -0
- package/packs/node-api.yml +7 -0
- package/packs/nx-monorepo.yml +6 -0
- package/packs/observability.yml +6 -0
- package/packs/owasp-asvs.yml +6 -0
- package/packs/owasp-llm.yml +8 -0
- package/packs/python.yml +6 -0
- package/packs/react.yml +6 -0
- package/packs/rust.yml +6 -0
- package/skills/lens-import/SKILL.md +185 -0
- package/skills/lens-import/references/conversion.md +96 -0
- package/skills/lens-import/scripts/check-import.mjs +154 -0
- package/skills/shepherd/SKILL.md +26 -5
- package/skills/shepherd/references/models.md +20 -7
- package/skills/shepherd/references/policy.md +9 -5
- package/skills/swarm/SKILL.md +11 -1
- package/skills/swarm/references/custom-lenses.md +50 -7
- package/src/cli.ts +96 -13
- package/src/config.ts +137 -21
- package/src/lens.ts +159 -8
- package/src/stack.ts +121 -0
- package/templates/shepherd-audit.yml +178 -0
- package/templates/shepherd-incident.yml +28 -4
- package/templates/shepherd.yml +32 -4
package/src/lens.ts
CHANGED
|
@@ -5,7 +5,9 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
|
|
|
5
5
|
import path from "node:path";
|
|
6
6
|
import { parse, stringify } from "yaml";
|
|
7
7
|
import { z } from "zod";
|
|
8
|
-
import { type Config, ConfigSchema, type Lens, LensSchema, lensCache, ModelId, TEAM_FILES } from "./config.ts";
|
|
8
|
+
import { type Config, ConfigSchema, type Lens, LensSchema, lensCache, ModelId, SEVERITIES, TEAM_FILES } from "./config.ts";
|
|
9
|
+
|
|
10
|
+
type Severity = (typeof SEVERITIES)[number];
|
|
9
11
|
|
|
10
12
|
export const BUILT_IN_LENSES = ["correctness", "security", "simplicity", "maintainability", "slop", "spec"];
|
|
11
13
|
|
|
@@ -29,7 +31,7 @@ export const repoLensFile = (repoRoot: string) => {
|
|
|
29
31
|
|
|
30
32
|
const readFile = (file: string): LensFile => (existsSync(file) ? LensFileSchema.parse(parse(readFileSync(file, "utf8")) ?? {}) : { lenses: {} });
|
|
31
33
|
|
|
32
|
-
export const readLenses = (file: string)
|
|
34
|
+
export const readLenses = (file: string) => readFile(file).lenses;
|
|
33
35
|
|
|
34
36
|
/**
|
|
35
37
|
* OpenCode agents for a harness whose subagent tool takes no model (OpenCode 1.x): one per rung,
|
|
@@ -37,7 +39,7 @@ export const readLenses = (file: string): Record<string, Lens> => readFile(file)
|
|
|
37
39
|
* OPENCODE_CONFIG_CONTENT; swarm and the loop then dispatch by agent name.
|
|
38
40
|
*/
|
|
39
41
|
export function opencodeAgents(choice: { ladder: string[] | null; models: Record<string, string> }) {
|
|
40
|
-
const agent = (model: string, about: string) => ({ mode: "subagent", model, description: `shepherd runner on ${model} (${about})` });
|
|
42
|
+
const agent = (model: string, about: string) => ({ mode: "subagent", model: opencodeModel(model), description: `shepherd runner on ${model} (${about})` });
|
|
41
43
|
|
|
42
44
|
return {
|
|
43
45
|
agent: Object.fromEntries([
|
|
@@ -47,6 +49,20 @@ export function opencodeAgents(choice: { ladder: string[] | null; models: Record
|
|
|
47
49
|
};
|
|
48
50
|
}
|
|
49
51
|
|
|
52
|
+
// stamp's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
|
|
53
|
+
const OPENCODE_PROVIDER = new Map([["bedrock", "amazon-bedrock"], ["vertex", "google-vertex"]]);
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* A model id as OpenCode spells it. stamp's canonical `provider:model` (`bedrock:eu.anthropic.claude-…-v1:0`)
|
|
57
|
+
* becomes `provider/model` (`amazon-bedrock/eu.anthropic.claude-…-v1:0`), so one ladder serves both tools.
|
|
58
|
+
* An OpenCode id or a Claude Code alias passes through.
|
|
59
|
+
*/
|
|
60
|
+
export function opencodeModel(id: string): string {
|
|
61
|
+
const m = /^([a-z][a-z0-9-]*):(.+)$/.exec(id);
|
|
62
|
+
|
|
63
|
+
return m ? `${OPENCODE_PROVIDER.get(m[1]!) ?? m[1]}/${m[2]}` : id;
|
|
64
|
+
}
|
|
65
|
+
|
|
50
66
|
/** Pin `name` (a lens or runner) to `model`, keeping everything else in the file. */
|
|
51
67
|
export function pinModel(file: string, name: string, model: string): void {
|
|
52
68
|
if (!LENS_NAME.test(name)) throw new Error(`"${name}" must be lowercase letters, digits, and dashes`);
|
|
@@ -55,6 +71,33 @@ export function pinModel(file: string, name: string, model: string): void {
|
|
|
55
71
|
write(file, { ...current, models: { ...current.models, [name]: ModelId.parse(model) } });
|
|
56
72
|
}
|
|
57
73
|
|
|
74
|
+
/** Name a model: `tier` becomes usable in the ladder and in pins, and swapping its model swaps it everywhere. */
|
|
75
|
+
export function setTier(file: string, tier: string, model: string): void {
|
|
76
|
+
if (!LENS_NAME.test(tier)) throw new Error(`"${tier}" must be lowercase letters, digits, and dashes`);
|
|
77
|
+
const current = readFile(file);
|
|
78
|
+
|
|
79
|
+
write(file, { ...current, tiers: { ...current.tiers, [tier]: ModelId.parse(model) } });
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// The environment variable each OpenCode provider reads its key from. SHEPHERD_API_KEY fills the one the session
|
|
83
|
+
// model's provider needs, so a single-provider team sets one secret.
|
|
84
|
+
const PROVIDER_KEY_ENV = new Map([
|
|
85
|
+
["opencode", "OPENCODE_API_KEY"],
|
|
86
|
+
["opencode-go", "OPENCODE_API_KEY"],
|
|
87
|
+
["anthropic", "ANTHROPIC_API_KEY"],
|
|
88
|
+
["openai", "OPENAI_API_KEY"],
|
|
89
|
+
["openrouter", "OPENROUTER_API_KEY"],
|
|
90
|
+
["deepseek", "DEEPSEEK_API_KEY"],
|
|
91
|
+
["groq", "GROQ_API_KEY"],
|
|
92
|
+
["mistral", "MISTRAL_API_KEY"],
|
|
93
|
+
["google", "GOOGLE_GENERATIVE_AI_API_KEY"],
|
|
94
|
+
["xai", "XAI_API_KEY"],
|
|
95
|
+
["amazon-bedrock", "AWS_BEARER_TOKEN_BEDROCK"],
|
|
96
|
+
]);
|
|
97
|
+
|
|
98
|
+
/** The key variable for an OpenCode model id's provider, or null when shepherd does not know it. */
|
|
99
|
+
export const providerKeyEnv = (opencodeId: string): string | null => PROVIDER_KEY_ENV.get(opencodeId.split("/")[0]!) ?? null;
|
|
100
|
+
|
|
58
101
|
/** Replace the ladder, cheapest model first. */
|
|
59
102
|
export function setLadder(file: string, ladder: string[]): void {
|
|
60
103
|
write(file, { ...readFile(file), ladder: z.array(ModelId).min(1).parse(ladder) });
|
|
@@ -97,7 +140,33 @@ fixes by its own rules. Nothing here can loosen shepherd's rules.
|
|
|
97
140
|
- Escalate: <changes that go to the author instead of being fixed>.
|
|
98
141
|
`;
|
|
99
142
|
|
|
100
|
-
|
|
143
|
+
// `- **<id>**: <rule>`, or `- **<id>** [refuse|escalate|note]: <rule>` to set that rule's severity for stamp.
|
|
144
|
+
const RULE = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*(?: \[(refuse|escalate|note)\])?:/gm;
|
|
145
|
+
|
|
146
|
+
export type LensRule = { id: string; severity?: Severity };
|
|
147
|
+
|
|
148
|
+
/** The rules in a lens's `## Review` section, with any severity tag; null when the section is missing. */
|
|
149
|
+
export function reviewRules(text: string): LensRule[] | null {
|
|
150
|
+
const review = /^## Review\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text.replace(/\r\n/g, "\n"))?.[1];
|
|
151
|
+
|
|
152
|
+
if (review === undefined) return null;
|
|
153
|
+
|
|
154
|
+
return [...review.matchAll(RULE)].map((m) => {
|
|
155
|
+
const rule: LensRule = { id: m[1]! };
|
|
156
|
+
const severity = z.enum(SEVERITIES).optional().parse(m[2]);
|
|
157
|
+
|
|
158
|
+
if (severity) rule.severity = severity;
|
|
159
|
+
|
|
160
|
+
return rule;
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Whether a lens entry's `only` and `disable` keep this rule. */
|
|
165
|
+
export const keepsRule = (lens: Pick<Lens, "only" | "disable">, id: string) => {
|
|
166
|
+
const hit = (globs: string[]) => globs.some((g) => new Bun.Glob(g).match(id));
|
|
167
|
+
|
|
168
|
+
return (!lens.only || hit(lens.only)) && !(lens.disable && hit(lens.disable));
|
|
169
|
+
};
|
|
101
170
|
|
|
102
171
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
|
|
103
172
|
|
|
@@ -112,17 +181,25 @@ export function lensProblems(lens: Lens, home: string, repoRoot: string): string
|
|
|
112
181
|
const problems: string[] = [];
|
|
113
182
|
|
|
114
183
|
if (front === undefined || !skillDescription(dir)) problems.push(`${file}: frontmatter needs a description`);
|
|
184
|
+
const ownLens = path.posix.normalize(lens.skill.replaceAll("\\", "/")).startsWith(".shepherd/lenses/");
|
|
115
185
|
|
|
116
|
-
|
|
117
|
-
|
|
186
|
+
// Rule ids are required under .shepherd/lenses/, and wherever only or disable must match them.
|
|
187
|
+
if (!ownLens && !lens.only && !lens.disable) return problems;
|
|
188
|
+
const rules = reviewRules(text);
|
|
118
189
|
|
|
119
|
-
if (
|
|
120
|
-
const ids =
|
|
190
|
+
if (rules === null) return [...problems, `${file}: add a "## Review" section`];
|
|
191
|
+
const ids = rules.map((r) => r.id);
|
|
121
192
|
|
|
122
193
|
if (ids.length === 0) problems.push(`${file}: "## Review" has no rules; write each as "- **<id>**: <rule>", the id lowercase with dashes`);
|
|
123
194
|
|
|
124
195
|
for (const id of new Set(ids.filter((id, i) => ids.indexOf(id) !== i))) problems.push(`${file}: rule id "${id}" is used more than once`);
|
|
125
196
|
|
|
197
|
+
for (const g of [...(lens.only ?? []), ...(lens.disable ?? [])]) {
|
|
198
|
+
if (!ids.some((id) => new Bun.Glob(g).match(id))) problems.push(`${file}: "${g}" in only or disable matches no rule id`);
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
if (ids.length && !ids.some((id) => keepsRule(lens, id))) problems.push(`${file}: only and disable leave no rule`);
|
|
202
|
+
|
|
126
203
|
return problems;
|
|
127
204
|
}
|
|
128
205
|
|
|
@@ -153,6 +230,64 @@ export function newLens(repoRoot: string, name: string, lens: Omit<Lens, "skill"
|
|
|
153
230
|
return dir;
|
|
154
231
|
}
|
|
155
232
|
|
|
233
|
+
/** The bundled packs (packs/<name>.yml): one starter lens each, with the files it applies to and its gate. */
|
|
234
|
+
export const PACKS_DIR = path.resolve(import.meta.dir, "..", "packs");
|
|
235
|
+
|
|
236
|
+
/** The lens entry a bundled pack declares for its own lens, minus the skill path. */
|
|
237
|
+
export function packLens(stack: string): Omit<Lens, "skill"> {
|
|
238
|
+
const { skill: _, ...rest } = LensSchema.parse(ConfigSchema.parse(parse(readFileSync(path.join(PACKS_DIR, `${stack}.yml`), "utf8"))).lenses[stack]);
|
|
239
|
+
|
|
240
|
+
return rest;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
// A dependency in any package.json that marks a stack. next implies react: its pack extends react's.
|
|
244
|
+
const NPM_STACKS: [RegExp, string[]][] = [
|
|
245
|
+
[/^next$/, ["react", "nextjs"]],
|
|
246
|
+
[/^(react|react-dom)$/, ["react"]],
|
|
247
|
+
[/^(express|fastify|hono|koa|@nestjs\/core)$/, ["node-api"]],
|
|
248
|
+
];
|
|
249
|
+
|
|
250
|
+
// A tracked file, anywhere in the repository, that marks a stack.
|
|
251
|
+
const FILE_STACKS: [RegExp, string][] = [
|
|
252
|
+
[/(^|\/)go\.mod$/, "go"],
|
|
253
|
+
[/(^|\/)Cargo\.toml$/, "rust"],
|
|
254
|
+
[/(^|\/)(pom\.xml|build\.gradle(\.kts)?)$/, "java"],
|
|
255
|
+
[/\.(csproj|fsproj|sln)$/, "dotnet"],
|
|
256
|
+
[/(^|\/)(pyproject\.toml|setup\.py|requirements\.txt)$/, "python"],
|
|
257
|
+
[/(^|\/)nx\.json$/, "nx-monorepo"],
|
|
258
|
+
];
|
|
259
|
+
|
|
260
|
+
const PackageJson = z.object({ dependencies: z.record(z.string(), z.string()).optional(), devDependencies: z.record(z.string(), z.string()).optional() });
|
|
261
|
+
|
|
262
|
+
/** JSON, or null when malformed: a broken package.json marks nothing. */
|
|
263
|
+
const parseJson = (text: string) => {
|
|
264
|
+
try {
|
|
265
|
+
return JSON.parse(text);
|
|
266
|
+
} catch {
|
|
267
|
+
return null;
|
|
268
|
+
}
|
|
269
|
+
};
|
|
270
|
+
|
|
271
|
+
/** The bundled stack packs this repository's tracked files point at, sorted by name. `files` is `git ls-files`. */
|
|
272
|
+
export function detectStacks(files: string[], read: (rel: string) => string | null): string[] {
|
|
273
|
+
const found = new Set<string>();
|
|
274
|
+
|
|
275
|
+
for (const f of files) {
|
|
276
|
+
for (const [re, stack] of FILE_STACKS) if (re.test(f)) found.add(stack);
|
|
277
|
+
|
|
278
|
+
if (!/(^|\/)package\.json$/.test(f)) continue;
|
|
279
|
+
const pkg = PackageJson.safeParse(parseJson(read(f) ?? "{}"));
|
|
280
|
+
const deps = pkg.success ? Object.keys({ ...pkg.data.dependencies, ...pkg.data.devDependencies }) : [];
|
|
281
|
+
|
|
282
|
+
for (const [re, stacks] of NPM_STACKS) if (deps.some((d) => re.test(d))) for (const s of stacks) found.add(s);
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
// ASVS holds for every language, so any detected stack brings it.
|
|
286
|
+
if (found.size) found.add("owasp-asvs");
|
|
287
|
+
|
|
288
|
+
return lensTemplates().filter((t) => found.has(t));
|
|
289
|
+
}
|
|
290
|
+
|
|
156
291
|
/** The directory holding the skill's SKILL.md: a path against the repository, or a name in the usual skills directories. */
|
|
157
292
|
export function resolveSkill(ref: string, home: string, repoRoot: string): string | null {
|
|
158
293
|
const pinned = lensCache(home, ref);
|
|
@@ -176,3 +311,19 @@ export function skillDescription(skillDir: string): string | null {
|
|
|
176
311
|
|
|
177
312
|
return parsed.success ? parsed.data.description.replace(/\s+/g, " ").trim() : null;
|
|
178
313
|
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* A detected stack's lens, copied from its starter into .shepherd/lenses/<stack> so the team owns and trims it,
|
|
317
|
+
* with the pack's applies_to and gate. An existing lens directory is kept as it is.
|
|
318
|
+
*/
|
|
319
|
+
export function stackLens(repoRoot: string, stack: string): Lens {
|
|
320
|
+
const skill = path.posix.join(".shepherd", "lenses", stack);
|
|
321
|
+
const dir = path.join(repoRoot, skill);
|
|
322
|
+
|
|
323
|
+
if (!existsSync(path.join(dir, "SKILL.md"))) {
|
|
324
|
+
mkdirSync(dir, { recursive: true });
|
|
325
|
+
writeFileSync(path.join(dir, "SKILL.md"), fromTemplate(stack, stack));
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
return { skill, ...packLens(stack) };
|
|
329
|
+
}
|
package/src/stack.ts
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
// Stacked PRs and wrong bases, detected the way stamp detects them before it reviews. A PR's base...head
|
|
2
|
+
// diff is what lands when it merges, which is right for a lone PR and wrong for two common shapes: a PR stacked on another open PR into the same base (its diff
|
|
3
|
+
// carries the parent's change), and a PR branched from one long-lived branch but opened against another
|
|
4
|
+
// (its diff carries everything the two branches differ by). Everything here is git ancestry on immutable
|
|
5
|
+
// SHAs; nothing a PR author writes (body, title, "stacked on #n") is read.
|
|
6
|
+
import { execFileSync } from "node:child_process";
|
|
7
|
+
import path from "node:path";
|
|
8
|
+
import { z } from "zod";
|
|
9
|
+
|
|
10
|
+
export type StackDeps = {
|
|
11
|
+
/** `git rev-list --topo-order <head> ^<base>`: this PR's commits, newest first. */
|
|
12
|
+
commits: (head: string, base: string) => string[];
|
|
13
|
+
/** How many of this PR's commits are not on `branch` (a remote-tracking ref). */
|
|
14
|
+
notOn: (head: string, base: string, branch: string) => number;
|
|
15
|
+
/** Remote branch names, `git ls-remote --heads origin`. */
|
|
16
|
+
branches: () => string[];
|
|
17
|
+
/** Fetch these branches into their remote-tracking refs. */
|
|
18
|
+
fetch: (branches: string[]) => void;
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
export type WrongBase = { branch: string; on: number; total: number };
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The long-lived branch this PR's commits mostly already sit on, when that is not its base: it was branched
|
|
25
|
+
* from there and opened against the wrong target. A branch holding every commit of the PR is not flagged
|
|
26
|
+
* (a backport or a promotion PR), and neither is the PR's own head branch.
|
|
27
|
+
*/
|
|
28
|
+
export function wrongBase(pr: { headSha: string; baseSha: string; baseRef: string; headRef: string }, longLived: string[], deps: StackDeps): WrongBase | null {
|
|
29
|
+
if (!longLived.length) return null;
|
|
30
|
+
const candidates = deps.branches().filter((b) => b !== pr.baseRef && b !== pr.headRef && longLived.some((g) => path.matchesGlob(b, g)));
|
|
31
|
+
|
|
32
|
+
if (!candidates.length) return null;
|
|
33
|
+
const total = deps.commits(pr.headSha, pr.baseSha).length;
|
|
34
|
+
|
|
35
|
+
if (total < 2) return null;
|
|
36
|
+
deps.fetch(candidates);
|
|
37
|
+
let worst: WrongBase | null = null;
|
|
38
|
+
|
|
39
|
+
for (const branch of candidates) {
|
|
40
|
+
const off = deps.notOn(pr.headSha, pr.baseSha, branch);
|
|
41
|
+
const on = total - off;
|
|
42
|
+
|
|
43
|
+
if (off > 0 && on * 2 > total && (!worst || on > worst.on)) worst = { branch, on, total };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
return worst;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The nearest open PR into the same base whose head is one of this PR's own commits: the parent this PR is
|
|
51
|
+
* stacked on. Its head being in base..head is the whole test, so a PR already merged into the base, or one
|
|
52
|
+
* that only shares history, never counts.
|
|
53
|
+
*/
|
|
54
|
+
export function stackedParent(pr: { number: number; headSha: string; baseSha: string }, open: { number: number; headRefOid: string }[], deps: Pick<StackDeps, "commits">): { parent: number; parentHead: string } | null {
|
|
55
|
+
const others = open.filter((p) => p.number !== pr.number && p.headRefOid !== pr.headSha);
|
|
56
|
+
|
|
57
|
+
if (!others.length) return null;
|
|
58
|
+
const order = deps.commits(pr.headSha, pr.baseSha);
|
|
59
|
+
let best: { parent: number; parentHead: string; at: number } | null = null;
|
|
60
|
+
|
|
61
|
+
for (const p of others) {
|
|
62
|
+
const at = order.indexOf(p.headRefOid);
|
|
63
|
+
|
|
64
|
+
if (at >= 0 && (!best || at < best.at)) best = { parent: p.number, parentHead: p.headRefOid, at };
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
return best && { parent: best.parent, parentHead: best.parentHead };
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// The same default stamp's policy carries: branches a PR is opened from and merged into, never feature branches.
|
|
71
|
+
export const LONG_LIVED = ["main", "master", "develop", "release", "release/*", "staging"];
|
|
72
|
+
|
|
73
|
+
const View = z.object({ number: z.number(), headRefName: z.string(), headRefOid: z.string(), baseRefName: z.string() });
|
|
74
|
+
|
|
75
|
+
const Open = z.array(z.object({ number: z.number(), headRefOid: z.string(), isCrossRepository: z.boolean() }));
|
|
76
|
+
|
|
77
|
+
export type Stack = {
|
|
78
|
+
pr: number;
|
|
79
|
+
head_sha: string;
|
|
80
|
+
base_ref: string;
|
|
81
|
+
/** Set when most of the PR's commits already sit on another long-lived branch: retarget it, review nothing. */
|
|
82
|
+
wrong_base: WrongBase | null;
|
|
83
|
+
/** The open PR this one is stacked on; review `range` instead of the whole PR. */
|
|
84
|
+
parent: { number: number; head: string } | null;
|
|
85
|
+
/** The git range to review: the delta over the parent, or base...head. */
|
|
86
|
+
range: string;
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
/** Fetch what the checks need (the PR head, its base, full history), then run them against GitHub's open PRs. */
|
|
90
|
+
export function prStack(number: number, repoRoot: string): Stack {
|
|
91
|
+
const run = (cmd: string, ...args: string[]) => execFileSync(cmd, args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 << 20 }).trim();
|
|
92
|
+
// Fetches authenticate through gh, since a CI checkout keeps no token for a private origin.
|
|
93
|
+
const git = (...args: string[]) => run("git", "-c", "credential.helper=", "-c", "credential.helper=!gh auth git-credential", ...args);
|
|
94
|
+
const view = View.parse(JSON.parse(run("gh", "pr", "view", String(number), "--json", "number,headRefName,headRefOid,baseRefName")));
|
|
95
|
+
const baseRef = `refs/remotes/origin/${view.baseRefName}`;
|
|
96
|
+
|
|
97
|
+
if (git("rev-parse", "--is-shallow-repository") === "true") git("fetch", "-q", "--unshallow", "origin");
|
|
98
|
+
git("fetch", "-q", "origin", `refs/pull/${number}/head`, `+refs/heads/${view.baseRefName}:${baseRef}`);
|
|
99
|
+
const baseSha = git("rev-parse", baseRef);
|
|
100
|
+
|
|
101
|
+
const deps: StackDeps = {
|
|
102
|
+
commits: (head, base) => git("rev-list", "--topo-order", head, `^${base}`).split("\n").filter(Boolean),
|
|
103
|
+
notOn: (head, base, branch) => Number(git("rev-list", "--count", head, `^${base}`, `^refs/remotes/origin/${branch}`)),
|
|
104
|
+
branches: () => git("ls-remote", "--heads", "origin").split("\n").flatMap((l) => l.split("\trefs/heads/")[1] ?? []),
|
|
105
|
+
fetch: (branches) => void git("fetch", "-q", "origin", ...branches.map((b) => `+refs/heads/${b}:refs/remotes/origin/${b}`)),
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
const pr = { number, headSha: view.headRefOid, baseSha, baseRef: view.baseRefName, headRef: view.headRefName };
|
|
109
|
+
const wrong = wrongBase(pr, LONG_LIVED, deps);
|
|
110
|
+
const open = wrong ? [] : Open.parse(JSON.parse(run("gh", "pr", "list", "--state", "open", "--base", view.baseRefName, "--limit", "100", "--json", "number,headRefOid,isCrossRepository"))).filter((p) => !p.isCrossRepository);
|
|
111
|
+
const parent = stackedParent(pr, open, deps);
|
|
112
|
+
|
|
113
|
+
return {
|
|
114
|
+
pr: number,
|
|
115
|
+
head_sha: view.headRefOid,
|
|
116
|
+
base_ref: view.baseRefName,
|
|
117
|
+
wrong_base: wrong,
|
|
118
|
+
parent: parent && { number: parent.parent, head: parent.parentHead },
|
|
119
|
+
range: `${parent?.parentHead ?? baseSha}...${view.headRefOid}`,
|
|
120
|
+
};
|
|
121
|
+
}
|
|
@@ -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
|
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
# CI on the PR installs and runs them), then opens the PR. The agent still holds the model key.
|
|
17
17
|
#
|
|
18
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.
|
|
20
|
-
# Variables: SHEPHERD_MODEL (
|
|
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/).
|
|
21
22
|
name: shepherd-incident
|
|
22
23
|
on:
|
|
23
24
|
workflow_run:
|
|
@@ -87,13 +88,36 @@ jobs:
|
|
|
87
88
|
timeout-minutes: 20 # opencode retries a provider error (an exhausted quota) silently; fail instead of holding the queue
|
|
88
89
|
env:
|
|
89
90
|
GH_TOKEN: ${{ github.token }}
|
|
91
|
+
SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
|
|
90
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 }}
|
|
91
105
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1"
|
|
92
106
|
OPENCODE_DISABLE_AUTOUPDATE: "1"
|
|
93
|
-
MODEL: ${{ vars.SHEPHERD_MODEL || 'opencode-go/kimi-k3' }}
|
|
94
107
|
HANDOFF: ${{ runner.temp }}/handoff
|
|
95
108
|
run: |
|
|
96
|
-
|
|
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
|
|
97
121
|
(a run URL, or an error or alert text).
|
|
98
122
|
You are running in GitHub Actions on the default branch, already checked out, with no push access.
|
|
99
123
|
At Step 6 do not push or open the PR: commit on incident/<issue>, write the PR title to $HANDOFF/pr-title.txt
|
package/templates/shepherd.yml
CHANGED
|
@@ -12,11 +12,16 @@
|
|
|
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
|
-
#
|
|
15
|
+
# SHEPHERD_API_KEY the model key, for whichever provider the session model names (Bedrock: a Bedrock API key).
|
|
16
|
+
# Or each provider's own secret (OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
|
|
17
|
+
# DEEPSEEK_API_KEY, AWS_BEARER_TOKEN_BEDROCK...) when the ladder mixes providers.
|
|
16
18
|
# SHEPHERD_NOTIFY_WEBHOOK optional: Slack Incoming Webhook or any JSON endpoint, told when a PR needs
|
|
17
19
|
# you, is ready to merge, or the iteration stopped on an error.
|
|
18
20
|
# Variables:
|
|
19
|
-
# SHEPHERD_MODEL
|
|
21
|
+
# SHEPHERD_MODEL optional: the session model, a model id or a tier from .shepherd/config.yml. Empty = the
|
|
22
|
+
# team's models.loop, else the top of its ladder, else opencode-go/kimi-k3. Runners take
|
|
23
|
+
# their own models from the team's tiers, ladder and pins (shepherd models shows them).
|
|
24
|
+
# AWS_REGION the Bedrock region, for a bedrock: model.
|
|
20
25
|
# SHEPHERD_LABEL optional: shepherd only PRs carrying this label. Whatever opens PRs (a person, Claude
|
|
21
26
|
# Code, Codex, another agent) hands one over by adding it.
|
|
22
27
|
# SHEPHERD_NOTIFY_ON optional: states that notify, e.g. "failure"; empty = success,failure,error.
|
|
@@ -219,12 +224,35 @@ jobs:
|
|
|
219
224
|
env:
|
|
220
225
|
GH_TOKEN: ${{ github.token }}
|
|
221
226
|
SHEPHERD_HANDOFF: ${{ runner.temp }}/handoff
|
|
227
|
+
SHEPHERD_API_KEY: ${{ secrets.SHEPHERD_API_KEY }} # one key, for the session model's provider
|
|
222
228
|
OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
|
|
229
|
+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
230
|
+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
231
|
+
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
|
|
232
|
+
DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
|
|
233
|
+
GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
|
|
234
|
+
MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
|
|
235
|
+
GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
|
|
236
|
+
XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
|
|
237
|
+
AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
|
|
238
|
+
AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
|
|
239
|
+
SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
|
|
240
|
+
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
223
241
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md are PR content
|
|
224
242
|
OPENCODE_DISABLE_AUTOUPDATE: "1"
|
|
225
|
-
MODEL: ${{ vars.SHEPHERD_MODEL || 'opencode-go/kimi-k3' }}
|
|
226
243
|
run: |
|
|
227
|
-
|
|
244
|
+
# The team's models, from the default branch: the session model, the variable its key goes in, and the
|
|
245
|
+
# OpenCode agents that carry the ladder and pins, so each runner gets its own model.
|
|
246
|
+
plan=$(shepherd ci-models)
|
|
247
|
+
model=$(jq -r .model <<<"$plan")
|
|
248
|
+
echo "session model: $model ($(jq -r .source <<<"$plan"))"
|
|
249
|
+
key_env=$(jq -r '.key_env // empty' <<<"$plan")
|
|
250
|
+
if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
|
|
251
|
+
unset SHEPHERD_API_KEY
|
|
252
|
+
# An unset secret arrives as "": a blank key would hide the provider's other credentials.
|
|
253
|
+
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
|
|
254
|
+
OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
|
|
255
|
+
opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
|
|
228
256
|
SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. You are running in GitHub Actions on the PR branch,
|
|
229
257
|
already checked out, and you cannot push. Nobody is watching this session: never wait for an answer. Anything you
|
|
230
258
|
would ask the user is deferred, listed in the iteration summary, and named in status.json. Do not schedule further
|