@jagreehal/shepherd 0.6.0 → 0.8.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/commands/shepherd.md +3 -2
- package/package.json +5 -2
- package/schema/config.json +340 -0
- package/skills/incident/SKILL.md +4 -2
- package/skills/shepherd/SKILL.md +40 -14
- package/skills/shepherd/references/dispatch.md +5 -3
- package/skills/shepherd/references/models.md +1 -1
- package/skills/swarm/SKILL.md +126 -83
- package/skills/swarm/references/custom-lenses.md +12 -4
- package/skills/swarm/references/formats.md +27 -37
- package/skills/triage/SKILL.md +5 -4
- package/src/cli.ts +187 -22
- package/src/config.ts +169 -2
- package/src/install.ts +52 -0
- package/src/lens.ts +33 -1
- package/src/summary.ts +117 -0
- package/templates/shepherd-audit.yml +39 -8
- package/templates/shepherd-incident.yml +36 -5
- package/templates/shepherd.yml +144 -23
package/src/install.ts
CHANGED
|
@@ -3,12 +3,64 @@
|
|
|
3
3
|
// may be the user's own skill that happens to share a name.
|
|
4
4
|
import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
|
|
5
5
|
import path from "node:path";
|
|
6
|
+
import { parse } from "yaml";
|
|
7
|
+
import { z } from "zod";
|
|
6
8
|
|
|
7
9
|
export const MARKER = ".shepherd-installed";
|
|
8
10
|
|
|
9
11
|
/** A workflow template with every `SHEPHERD_VERSION:` pin set to `version`, so each job runs the CLI that wrote it. */
|
|
10
12
|
export const pinWorkflow = (text: string, version: string) => text.replaceAll(/SHEPHERD_VERSION: \S+/g, `SHEPHERD_VERSION: ${version}`);
|
|
11
13
|
|
|
14
|
+
/** Run the model job in a GitHub environment, so model keys stored as its secrets reach that job and no other. */
|
|
15
|
+
export function environmentWorkflow(text: string, name: string): string {
|
|
16
|
+
// The name lands in YAML: refuse anything that could end the scalar or start a new key.
|
|
17
|
+
if (!/^[\w.-]+$/.test(name)) throw new Error(`--environment "${name}": use letters, digits, ".", "_" and "-"`);
|
|
18
|
+
|
|
19
|
+
return text.replaceAll(/^( +)# environment: <name>.*$/gm, `$1environment: ${name} # the model keys are this environment's secrets: no other job reads them`);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* A workflow rewritten from its current template, keeping what the installer or the team chose in the old copy: the
|
|
24
|
+
* model job's environment and the `workflows:` list naming their CI. Everything else is the template's.
|
|
25
|
+
*/
|
|
26
|
+
export function upgradeWorkflow(template: string, existing: string, version: string, environment?: string) {
|
|
27
|
+
const kept: string[] = [];
|
|
28
|
+
|
|
29
|
+
// Read as YAML, not by pattern: a quoted environment or a multiline workflows list is just as valid, and losing
|
|
30
|
+
// either takes the model's keys away or stops reviews. Anything this cannot carry over refuses the upgrade.
|
|
31
|
+
const old = z
|
|
32
|
+
.object({
|
|
33
|
+
on: z.object({ workflow_run: z.object({ workflows: z.array(z.string()).min(1) }).optional() }).optional(),
|
|
34
|
+
jobs: z.record(z.string(), z.object({ environment: z.union([z.string(), z.object({ name: z.string() }).transform((e) => e.name)]).optional() })),
|
|
35
|
+
})
|
|
36
|
+
.safeParse(parse(existing));
|
|
37
|
+
|
|
38
|
+
if (!old.success) throw new Error(`cannot read its environment and workflows list (${old.error.issues[0]?.path.join(".")}): update it by hand`);
|
|
39
|
+
|
|
40
|
+
const envs = [...new Set(Object.values(old.data.jobs).flatMap((j) => (j.environment === undefined ? [] : [j.environment])))];
|
|
41
|
+
|
|
42
|
+
if (!environment && envs.length > 1) throw new Error(`its jobs use different environments (${envs.join(", ")}): update it by hand`);
|
|
43
|
+
|
|
44
|
+
const env = environment ?? envs[0];
|
|
45
|
+
let text = pinWorkflow(template, version);
|
|
46
|
+
|
|
47
|
+
if (env) {
|
|
48
|
+
text = environmentWorkflow(text, env);
|
|
49
|
+
kept.push(`environment ${env}`);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const workflows = old.data.on?.workflow_run?.workflows;
|
|
53
|
+
|
|
54
|
+
if (workflows && /^ +workflows: \[.*\]\s*$/m.test(text)) {
|
|
55
|
+
const list = `[${workflows.map((w) => (/^[\w.-]+$/.test(w) ? w : JSON.stringify(w))).join(", ")}]`;
|
|
56
|
+
|
|
57
|
+
text = text.replace(/^( +workflows: )\[.*\]\s*$/m, `$1${list}`);
|
|
58
|
+
kept.push(`workflows ${list}`);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return { text, kept };
|
|
62
|
+
}
|
|
63
|
+
|
|
12
64
|
// Command files are single files, so they carry the marker as a comment line instead.
|
|
13
65
|
const COMMAND_MARKER = "<!-- shepherd-installed -->";
|
|
14
66
|
|
package/src/lens.ts
CHANGED
|
@@ -49,6 +49,26 @@ export function opencodeAgents(choice: { ladder: string[] | null; models: Record
|
|
|
49
49
|
};
|
|
50
50
|
}
|
|
51
51
|
|
|
52
|
+
// OpenCode's own agents, which pick a model of their own when nothing names one (on Bedrock, a `global.` profile that
|
|
53
|
+
// can leave the region).
|
|
54
|
+
const OPENCODE_BUILT_INS = ["build", "plan", "general", "explore", "title", "summary", "compaction"];
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* OpenCode's config for a CI run: shepherd's agents, every built-in agent and the small model on the session model, and
|
|
58
|
+
* only the providers the plan names enabled. PR content never reaches a provider or model the team did not choose.
|
|
59
|
+
*/
|
|
60
|
+
export function ciOpencodeConfig(session: string, choice: { ladder: string[] | null; models: Record<string, string> }) {
|
|
61
|
+
const { agent } = opencodeAgents(choice);
|
|
62
|
+
const models = [session, ...Object.values(agent).map((a) => a.model)];
|
|
63
|
+
|
|
64
|
+
return {
|
|
65
|
+
model: session,
|
|
66
|
+
small_model: session,
|
|
67
|
+
enabled_providers: [...new Set(models.map((m) => m.split("/")[0]!))].sort(),
|
|
68
|
+
agent: { ...Object.fromEntries(OPENCODE_BUILT_INS.map((name) => [name, { model: session }])), ...agent },
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
52
72
|
// stamp's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
|
|
53
73
|
const OPENCODE_PROVIDER = new Map([["bedrock", "amazon-bedrock"], ["vertex", "google-vertex"]]);
|
|
54
74
|
|
|
@@ -71,6 +91,13 @@ export function pinModel(file: string, name: string, model: string): void {
|
|
|
71
91
|
write(file, { ...current, models: { ...current.models, [name]: ModelId.parse(model) } });
|
|
72
92
|
}
|
|
73
93
|
|
|
94
|
+
/** Set CI settings under `ci:`, keeping everything else in the file. ConfigSchema checks them as it reads them back. */
|
|
95
|
+
export function setCi(file: string, values: Record<string, string>): void {
|
|
96
|
+
const current = readFile(file);
|
|
97
|
+
|
|
98
|
+
write(file, ConfigSchema.parse({ ...current, ci: { ...current.ci, ...values } }));
|
|
99
|
+
}
|
|
100
|
+
|
|
74
101
|
/** Name a model: `tier` becomes usable in the ladder and in pins, and swapping its model swaps it everywhere. */
|
|
75
102
|
export function setTier(file: string, tier: string, model: string): void {
|
|
76
103
|
if (!LENS_NAME.test(tier)) throw new Error(`"${tier}" must be lowercase letters, digits, and dashes`);
|
|
@@ -95,6 +122,8 @@ const PROVIDER_KEY_ENV = new Map([
|
|
|
95
122
|
["amazon-bedrock", "AWS_BEARER_TOKEN_BEDROCK"],
|
|
96
123
|
]);
|
|
97
124
|
|
|
125
|
+
export const PROVIDER_KEY_ENVS = [...PROVIDER_KEY_ENV.values()];
|
|
126
|
+
|
|
98
127
|
/** The key variable for an OpenCode model id's provider, or null when shepherd does not know it. */
|
|
99
128
|
export const providerKeyEnv = (opencodeId: string): string | null => PROVIDER_KEY_ENV.get(opencodeId.split("/")[0]!) ?? null;
|
|
100
129
|
|
|
@@ -104,8 +133,11 @@ export function setLadder(file: string, ladder: string[]): void {
|
|
|
104
133
|
}
|
|
105
134
|
|
|
106
135
|
function write(file: string, contents: LensFile): void {
|
|
136
|
+
// The file's leading comments, the editor's $schema line among them, survive every edit.
|
|
137
|
+
const head = existsSync(file) ? (/^(?:#.*\n)*/.exec(readFileSync(file, "utf8"))?.[0] ?? "") : "";
|
|
138
|
+
|
|
107
139
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
108
|
-
writeFileSync(file, stringify(contents));
|
|
140
|
+
writeFileSync(file, head + stringify(contents));
|
|
109
141
|
}
|
|
110
142
|
|
|
111
143
|
/** Add or replace one lens, keeping every other entry in the file. */
|
package/src/summary.ts
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Swarm's summary comment, rendered in code from the round's JSON. The comment keeps the same shape every round, so a
|
|
3
|
+
* reader scans one line per section and garden parses the heading. Every model-written string is defused here.
|
|
4
|
+
*/
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
import type { BRANDING } from "./config.ts";
|
|
7
|
+
|
|
8
|
+
const Severity = z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW", "NIT"]);
|
|
9
|
+
|
|
10
|
+
export const SummaryInput = z.object({
|
|
11
|
+
head_sha: z.string().regex(/^[0-9a-f]{7,40}$/),
|
|
12
|
+
verdict: z.enum(["blocked", "changes", "nits", "good"]),
|
|
13
|
+
why: z.string(),
|
|
14
|
+
findings: z.array(z.object({ file: z.string().default(""), line: z.union([z.number().int().nonnegative(), z.string().regex(/^(?:\d+(?:-\d+)?|general)$/)]).optional(), severity: Severity, lens: z.string(), body: z.string(), convergent: z.boolean().default(false) })).default([]),
|
|
15
|
+
still_open: z.array(z.object({ url: z.string().regex(/^https:\/\/github\.com\/[\w./#-]+$/), title: z.string() })).default([]),
|
|
16
|
+
checks: z.array(z.object({ tool: z.string(), status: z.enum(["ran", "unavailable"]), findings: z.number().default(0), reason: z.string().optional() })).default([]),
|
|
17
|
+
lenses: z.array(z.object({ lens: z.string(), model: z.string().default(""), scope: z.union([z.string(), z.array(z.string())]).default("full"), status: z.enum(["ok", "failed", "could_not_run"]), take: z.string().default(""), skill_blob: z.string().default("") })).default([]),
|
|
18
|
+
lenses_yml_blob: z.string().default(""),
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
export type SummaryInput = z.input<typeof SummaryInput>;
|
|
22
|
+
|
|
23
|
+
type Emoji = Record<keyof typeof BRANDING.emoji, string>;
|
|
24
|
+
|
|
25
|
+
const VERDICT = { blocked: ["blocked", "BLOCKED"], changes: ["changes_needed", "CHANGES NEEDED"], nits: ["approve_with_nits", "APPROVE WITH NITS"], good: ["looks_good", "LOOKS GOOD"] } as const;
|
|
26
|
+
|
|
27
|
+
const SEVERITIES = Severity.options;
|
|
28
|
+
|
|
29
|
+
const GLYPH = { CRITICAL: "critical", HIGH: "high", MEDIUM: "medium", LOW: "low", NIT: "nit" } as const satisfies Record<z.infer<typeof Severity>, keyof Emoji>;
|
|
30
|
+
|
|
31
|
+
/** Model text made inert: no hidden markers, mentions, images or control characters, one table cell when `cell`. */
|
|
32
|
+
export function defuse(text: string, cell = false): string {
|
|
33
|
+
const out = text
|
|
34
|
+
.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
|
|
35
|
+
.replaceAll("<!--", "<!--")
|
|
36
|
+
.replace(/<(\/?)(img|picture|source|video|iframe|details|summary)\b/gi, "<$1$2")
|
|
37
|
+
.replace(/!\[([^\]]*)\]\([^)]*\)/g, "[image removed: $1]")
|
|
38
|
+
.replaceAll("![", "!\\[") // reference-style images too: `![x][ref]` with a `[ref]: url` line elsewhere
|
|
39
|
+
.replace(/(?<![\w/])@(?=[A-Za-z0-9])/g,"@");
|
|
40
|
+
|
|
41
|
+
return cell ? out.replace(/\r?\n/g, " ").replaceAll("|", "\\|") : out;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** The latest round of a summary already on the PR, folded into one history line, plus the history it carried. */
|
|
45
|
+
export function earlierRounds(previous: string | undefined) {
|
|
46
|
+
if (!previous) return { round: 0, history: [] };
|
|
47
|
+
|
|
48
|
+
const latest = /^## \S+ ([A-Z_ ]+?) <sub>\((?:round (\d+)|handoff) @ ([0-9a-f]{7,40})\)<\/sub>/m.exec(previous);
|
|
49
|
+
const carried = previous.match(/^(?:round \d+|handoff) @ [0-9a-f]{7,40}: [^\n]{0,200}$/gm) ?? [];
|
|
50
|
+
const round = Number(latest?.[2] ?? Math.max(0, ...carried.map((l) => Number(/^round (\d+)/.exec(l)?.[1] ?? 0))));
|
|
51
|
+
|
|
52
|
+
return { round, history: [...(latest ? [`${latest[2] ? `round ${latest[2]}` : "handoff"} @ ${latest[3]}: ${latest[1]}`] : []), ...carried] };
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const section = (summary: string, body: string[], open = false) => [`<details${open ? " open" : ""}>`, `<summary>${summary}</summary>`, "", ...body, "", "</details>", ""];
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
|
|
59
|
+
* it is the body alone, for the handoff file the publish job wraps in its own marker and header.
|
|
60
|
+
*/
|
|
61
|
+
export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string): string {
|
|
62
|
+
const s = SummaryInput.parse(raw);
|
|
63
|
+
const [key, label] = VERDICT[s.verdict];
|
|
64
|
+
const { round, history } = earlierRounds(previous);
|
|
65
|
+
const sha = s.head_sha.slice(0, 7);
|
|
66
|
+
const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
|
|
67
|
+
const where = (f: (typeof s.findings)[number]) => (f.file ? ` · \`${defuse(f.file, true).replaceAll("`", "")}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}\`` : "");
|
|
68
|
+
|
|
69
|
+
const findings = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev));
|
|
70
|
+
|
|
71
|
+
const counts = SEVERITIES.flatMap((sev) => {
|
|
72
|
+
const n = s.findings.filter((f) => f.severity === sev).length;
|
|
73
|
+
|
|
74
|
+
return n ? [`${glyph(sev)} ${n} ${sev}`] : [];
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
const ran = s.checks.filter((c) => c.status === "ran");
|
|
78
|
+
const failed = s.lenses.filter((l) => l.status !== "ok");
|
|
79
|
+
const out = [...(header === null ? [] : ["<!-- shepherd-swarm-summary -->", "> [!NOTE]", header, ""]), `## ${emoji[key]} ${label} <sub>(round ${round + 1} @ ${sha})</sub>`, "", defuse(s.why), ""];
|
|
80
|
+
|
|
81
|
+
out.push(
|
|
82
|
+
...section(
|
|
83
|
+
`<strong>Findings:</strong> ${counts.join(" · ") || "none"}`,
|
|
84
|
+
findings.length ? findings.flatMap((f) => [`**${glyph(f.severity)} ${f.severity}**${where(f)} · ${f.convergent ? "convergent: " : ""}${defuse(f.lens, true)}`, "", defuse(f.body), ""]) : ["Nothing this round."],
|
|
85
|
+
s.verdict !== "good",
|
|
86
|
+
),
|
|
87
|
+
);
|
|
88
|
+
|
|
89
|
+
if (s.still_open.length) out.push(...section(`<strong>Still open:</strong> ${s.still_open.length}`, s.still_open.map((t) => `- [${defuse(t.title, true).replace(/[[\]]/g, "")}](${t.url})`)));
|
|
90
|
+
|
|
91
|
+
if (s.checks.length) {
|
|
92
|
+
const skipped = s.checks.length - ran.length;
|
|
93
|
+
|
|
94
|
+
out.push(
|
|
95
|
+
...section(
|
|
96
|
+
`<strong>Checks:</strong> ${ran.length} ran${skipped ? ` · ⏭️ ${skipped} skipped` : ""}`,
|
|
97
|
+
s.checks.map((c) => (c.status === "ran" ? `- ${defuse(c.tool, true)}: ${c.findings} finding${c.findings === 1 ? "" : "s"}` : `- checks skipped: ${defuse(c.tool, true)} (${defuse(c.reason ?? "unavailable", true)})`)),
|
|
98
|
+
),
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (s.lenses.length) {
|
|
103
|
+
out.push(
|
|
104
|
+
...section(`<strong>Lenses:</strong> ${s.lenses.length - failed.length} ok${failed.length ? ` · ❌ ${failed.length} did not finish` : ""}`, [
|
|
105
|
+
"| Lens | Model | Scope | Status | Take | SKILL.md |",
|
|
106
|
+
"| --- | --- | --- | --- | --- | --- |",
|
|
107
|
+
...s.lenses.map((l) => `| ${[l.lens, l.model, Array.isArray(l.scope) ? l.scope.join(", ") : l.scope, l.status, l.take, l.skill_blob.slice(0, 7)].map((c) => defuse(c, true)).join(" | ")} |`),
|
|
108
|
+
...(s.lenses_yml_blob ? ["", `<sub>lenses.yml ${defuse(s.lenses_yml_blob.slice(0, 7), true)}</sub>`] : []),
|
|
109
|
+
]),
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// The handoff body (no header) leaves history to the publish job, which folds in the comment it replaces.
|
|
114
|
+
if (history.length && header !== null) out.push(...section(`Earlier rounds (${history.length})`, [defuse(history.join("\n"))]));
|
|
115
|
+
|
|
116
|
+
return out.join("\n").trimEnd() + "\n";
|
|
117
|
+
}
|
|
@@ -10,9 +10,10 @@
|
|
|
10
10
|
# report then becomes a public artifact.
|
|
11
11
|
#
|
|
12
12
|
# Secrets: SHEPHERD_API_KEY (or the provider's own key) for the model.
|
|
13
|
-
# Variables: SHEPHERD_MODEL (
|
|
14
|
-
# AUDIT_PLAYS (space-separated play names; empty = the default
|
|
15
|
-
# AUDIT_PUBLIC (`true` to run on a public repository, publishing the report).
|
|
13
|
+
# Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
|
|
14
|
+
# AUDIT_PLAYS (ci.audit.plays; space-separated play names; empty = the default),
|
|
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.
|
|
16
17
|
name: shepherd-audit
|
|
17
18
|
on:
|
|
18
19
|
schedule:
|
|
@@ -20,7 +21,7 @@ on:
|
|
|
20
21
|
workflow_dispatch:
|
|
21
22
|
inputs:
|
|
22
23
|
plays:
|
|
23
|
-
description: Plays to run, space-separated (empty = AUDIT_PLAYS or the default)
|
|
24
|
+
description: Plays to run, space-separated (empty = ci.audit.plays, AUDIT_PLAYS, or the default)
|
|
24
25
|
required: false
|
|
25
26
|
|
|
26
27
|
permissions: {}
|
|
@@ -34,7 +35,30 @@ jobs:
|
|
|
34
35
|
outputs:
|
|
35
36
|
private: ${{ steps.repo.outputs.private }}
|
|
36
37
|
default_branch: ${{ steps.repo.outputs.default_branch }}
|
|
38
|
+
audit_public: ${{ steps.settings.outputs.audit_public }}
|
|
39
|
+
audit_plays: ${{ steps.settings.outputs.audit_plays }}
|
|
40
|
+
aws_region: ${{ steps.settings.outputs.aws_region }}
|
|
41
|
+
env:
|
|
42
|
+
SHEPHERD_VERSION: 0.3.0 # pinned, as in audit
|
|
37
43
|
steps:
|
|
44
|
+
# Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
|
|
45
|
+
- uses: actions/checkout@v4
|
|
46
|
+
with:
|
|
47
|
+
ref: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
48
|
+
sparse-checkout: .shepherd
|
|
49
|
+
persist-credentials: false
|
|
50
|
+
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
|
|
51
|
+
- name: Settings
|
|
52
|
+
id: settings
|
|
53
|
+
env:
|
|
54
|
+
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
55
|
+
GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
|
|
56
|
+
AWS_REGION: ${{ vars.AWS_REGION }}
|
|
57
|
+
AUDIT_PLAYS: ${{ vars.AUDIT_PLAYS }}
|
|
58
|
+
AUDIT_PUBLIC: ${{ vars.AUDIT_PUBLIC }}
|
|
59
|
+
run: |
|
|
60
|
+
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
61
|
+
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
|
38
62
|
- id: repo
|
|
39
63
|
shell: bash
|
|
40
64
|
env:
|
|
@@ -43,8 +67,9 @@ jobs:
|
|
|
43
67
|
|
|
44
68
|
audit:
|
|
45
69
|
needs: repo
|
|
46
|
-
if: needs.repo.outputs.private == 'true' ||
|
|
70
|
+
if: needs.repo.outputs.private == 'true' || needs.repo.outputs.audit_public == 'true'
|
|
47
71
|
runs-on: ubuntu-latest
|
|
72
|
+
# environment: <name> `shepherd workflows --environment <name>`: store the model keys as that environment's secrets, readable by this job only
|
|
48
73
|
timeout-minutes: 60
|
|
49
74
|
concurrency:
|
|
50
75
|
group: shepherd-audit
|
|
@@ -54,7 +79,7 @@ jobs:
|
|
|
54
79
|
env:
|
|
55
80
|
SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
|
|
56
81
|
PLAYBOOK_SHA: 65d4efd2cd0b081d52101e9708792b944e4ddebb # OWASP/secure-agent-playbook, pinned: the plays are instructions
|
|
57
|
-
PLAYS: ${{ github.event.inputs.plays ||
|
|
82
|
+
PLAYS: ${{ github.event.inputs.plays || needs.repo.outputs.audit_plays }}
|
|
58
83
|
steps:
|
|
59
84
|
- uses: actions/checkout@v4
|
|
60
85
|
with:
|
|
@@ -98,7 +123,7 @@ jobs:
|
|
|
98
123
|
GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
|
|
99
124
|
XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
|
|
100
125
|
AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
|
|
101
|
-
AWS_REGION: ${{
|
|
126
|
+
AWS_REGION: ${{ needs.repo.outputs.aws_region }} # ci.aws_region or the AWS_REGION variable, for a bedrock: model
|
|
102
127
|
SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
|
|
103
128
|
SHEPHERD_DEFAULT_BRANCH: ${{ needs.repo.outputs.default_branch }}
|
|
104
129
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md stay out of the agent's config
|
|
@@ -127,6 +152,8 @@ jobs:
|
|
|
127
152
|
then each finding with severity, CWE, file:line and the fix. Never write a secret's value: name its type, file and
|
|
128
153
|
line, and the first 4 characters at most. Nobody is watching this session: never wait for an answer."
|
|
129
154
|
test -s "$RUNNER_TEMP/audit/report.md" || { echo "::error::the audit wrote no report"; exit 1; }
|
|
155
|
+
# The team's branding, from the default branch, for the report job's header.
|
|
156
|
+
shepherd branding | jq -r .headers.audit > "$RUNNER_TEMP/audit/header.md" || rm -f "$RUNNER_TEMP/audit/header.md"
|
|
130
157
|
- name: Withhold a report that carries a credential
|
|
131
158
|
shell: bash
|
|
132
159
|
run: |
|
|
@@ -173,7 +200,11 @@ jobs:
|
|
|
173
200
|
echo "Public repository (AUDIT_PUBLIC): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
|
|
174
201
|
exit 0
|
|
175
202
|
fi
|
|
176
|
-
|
|
203
|
+
# The header came out of a job a model ran in: one line with the automated prefix, or the default.
|
|
204
|
+
header='> 🤖 Automated comment by **Shepherd audit**, not written by a human'
|
|
205
|
+
custom=$(head -c 400 audit/header.md 2>/dev/null || true)
|
|
206
|
+
if [[ "$custom" == "> 🤖 Automated comment by "* && "$custom" != *$'\n'* ]]; then header=$custom; fi
|
|
207
|
+
body=$(printf '%s\n\nRun: %s\n\n%s' "$header" "$RUN_URL" "$(head -c 60000 audit/report.md)")
|
|
177
208
|
gh label create shepherd-audit --repo "$REPO" --color B60205 --description "shepherd's scheduled security audit" 2>/dev/null || true
|
|
178
209
|
issue=$(gh issue list --repo "$REPO" --label shepherd-audit --state open --json number --jq '.[0].number // empty')
|
|
179
210
|
if [ -n "$issue" ]; then gh issue comment "$issue" --repo "$REPO" --body "$body"
|
|
@@ -17,8 +17,8 @@
|
|
|
17
17
|
#
|
|
18
18
|
# Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and stamp;
|
|
19
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 (
|
|
21
|
-
# INCIDENT_PATHS (
|
|
20
|
+
# Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
|
|
21
|
+
# INCIDENT_PATHS (ci.incident_paths in .shepherd/config.yml; the variable overrides it; empty = ^src/).
|
|
22
22
|
name: shepherd-incident
|
|
23
23
|
on:
|
|
24
24
|
workflow_run:
|
|
@@ -42,6 +42,7 @@ jobs:
|
|
|
42
42
|
&& github.event.workflow_run.head_branch == github.event.repository.default_branch)
|
|
43
43
|
|| github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
|
|
44
44
|
runs-on: ubuntu-latest
|
|
45
|
+
# environment: <name> `shepherd workflows --environment <name>`: store the model keys as that environment's secrets, readable by this job only
|
|
45
46
|
timeout-minutes: 45
|
|
46
47
|
# On the job, not the workflow: every green CI run starts this workflow and skips, and a workflow-level group
|
|
47
48
|
# would hand that skip the one pending slot a real incident needs. One at a time, so a repeat signal dedupes.
|
|
@@ -99,7 +100,7 @@ jobs:
|
|
|
99
100
|
GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
|
|
100
101
|
XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
|
|
101
102
|
AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
|
|
102
|
-
AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
|
|
103
|
+
AWS_REGION: ${{ vars.AWS_REGION }} # overrides ci.aws_region, for a bedrock: model
|
|
103
104
|
SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
|
|
104
105
|
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
105
106
|
OPENCODE_DISABLE_PROJECT_CONFIG: "1"
|
|
@@ -109,6 +110,7 @@ jobs:
|
|
|
109
110
|
# The team's models, from the default branch: the session model, the variable its key goes in, and the
|
|
110
111
|
# OpenCode agents that carry the ladder and pins, so each runner gets its own model.
|
|
111
112
|
plan=$(shepherd ci-models)
|
|
113
|
+
AWS_REGION=$(shepherd ci-settings | jq -r .aws_region.value) && export AWS_REGION # ci.aws_region, or the variable
|
|
112
114
|
model=$(jq -r .model <<<"$plan")
|
|
113
115
|
echo "session model: $model ($(jq -r .source <<<"$plan"))"
|
|
114
116
|
key_env=$(jq -r '.key_env // empty' <<<"$plan")
|
|
@@ -139,11 +141,39 @@ jobs:
|
|
|
139
141
|
path: ${{ runner.temp }}/handoff
|
|
140
142
|
if-no-files-found: ignore
|
|
141
143
|
|
|
142
|
-
|
|
144
|
+
# The paths a fix may change, resolved in a job with no model and no secret: the model cannot choose them.
|
|
145
|
+
settings:
|
|
143
146
|
needs: investigate
|
|
144
147
|
runs-on: ubuntu-latest
|
|
148
|
+
permissions:
|
|
149
|
+
contents: read
|
|
150
|
+
outputs:
|
|
151
|
+
incident_paths: ${{ steps.settings.outputs.incident_paths }}
|
|
152
|
+
env:
|
|
153
|
+
SHEPHERD_VERSION: 0.3.0 # pinned, as in investigate
|
|
154
|
+
steps:
|
|
155
|
+
# Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
|
|
156
|
+
- uses: actions/checkout@v4
|
|
157
|
+
with:
|
|
158
|
+
ref: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
159
|
+
sparse-checkout: .shepherd
|
|
160
|
+
persist-credentials: false
|
|
161
|
+
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
|
|
162
|
+
- name: Settings
|
|
163
|
+
id: settings
|
|
164
|
+
env:
|
|
165
|
+
SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
|
|
166
|
+
GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
|
|
167
|
+
INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS }}
|
|
168
|
+
run: |
|
|
169
|
+
bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
|
|
170
|
+
"$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
|
|
171
|
+
|
|
172
|
+
open:
|
|
173
|
+
needs: [investigate, settings]
|
|
174
|
+
runs-on: ubuntu-latest
|
|
145
175
|
env:
|
|
146
|
-
INCIDENT_PATHS: ${{
|
|
176
|
+
INCIDENT_PATHS: ${{ needs.settings.outputs.incident_paths }} # extended regex every changed path must match
|
|
147
177
|
permissions:
|
|
148
178
|
contents: write
|
|
149
179
|
pull-requests: write
|
|
@@ -176,6 +206,7 @@ jobs:
|
|
|
176
206
|
# its own so a failure stops here instead of passing an empty list; an empty change is refused too.
|
|
177
207
|
git diff -z --no-renames --name-only "origin/$DEFAULT...$branch" > ../changed
|
|
178
208
|
[ -s ../changed ] || { echo "::error::$branch changes nothing"; exit 1; }
|
|
209
|
+
[ -n "$INCIDENT_PATHS" ] || { echo "::error::no INCIDENT_PATHS: an empty pattern would allow every path"; exit 1; }
|
|
179
210
|
outside=$(tr '\0' '\n' < ../changed | grep -Ev -- "$INCIDENT_PATHS" || [ $? -eq 1 ])
|
|
180
211
|
[ -z "$outside" ] || { echo "::error::the fix changes paths outside $INCIDENT_PATHS; a person should look:"; echo "$outside"; exit 1; }
|
|
181
212
|
git push origin "$branch:refs/heads/$branch"
|