@thegpvc/gp-foundry 0.2.16 → 0.3.1
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 +8 -1
- package/README.md +37 -2
- package/actions/config-loader/dist/index.cjs +1 -1
- package/actions/merge-gate/README.md +51 -3
- package/actions/merge-gate/action.yml +32 -3
- package/actions/merge-gate/dist/index.cjs +61 -58
- package/actions/pr-scope/README.md +36 -0
- package/actions/pr-scope/action.yml +76 -0
- package/actions/pr-scope/dist/index.cjs +70 -0
- package/dist/cli/index.cjs +148 -106
- package/package.json +1 -1
- package/schema/config.schema.json +32 -2
- package/skill/SKILL.md +11 -2
- package/skill/reference/node-types.md +38 -4
- package/skill/templates/foundry.config.yaml +21 -2
- package/skill/templates/harness.dot +9 -5
- package/skill/templates/policy-merge.yaml +14 -3
package/package.json
CHANGED
|
@@ -112,6 +112,28 @@
|
|
|
112
112
|
}
|
|
113
113
|
}
|
|
114
114
|
},
|
|
115
|
+
"rollout": {
|
|
116
|
+
"type": "object",
|
|
117
|
+
"additionalProperties": false,
|
|
118
|
+
"description": "The rollout dial: which human PRs the pipeline looks at while it is brought to a repo gradually. Leave the block out and every PR is in scope. PRs the harness bot opened are always in scope; drafts and other bots' PRs never are (a bot is reviewed only if named in authors).",
|
|
119
|
+
"properties": {
|
|
120
|
+
"authors": {
|
|
121
|
+
"type": "array",
|
|
122
|
+
"items": { "type": "string", "minLength": 1 },
|
|
123
|
+
"description": "GitHub logins whose PRs are in scope. Case-insensitive."
|
|
124
|
+
},
|
|
125
|
+
"opt_in_label": {
|
|
126
|
+
"type": "string",
|
|
127
|
+
"minLength": 1,
|
|
128
|
+
"description": "A PR carrying this label is in scope, whoever opened it. A key of `labels`, or a literal label name."
|
|
129
|
+
},
|
|
130
|
+
"skip_label": {
|
|
131
|
+
"type": "string",
|
|
132
|
+
"minLength": 1,
|
|
133
|
+
"description": "A PR carrying this label is never in scope. A key of `labels`, or a literal label name."
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
},
|
|
115
137
|
"labels": {
|
|
116
138
|
"type": "object",
|
|
117
139
|
"description": "semantic role -> repo label (the drift-killer).",
|
|
@@ -144,8 +166,16 @@
|
|
|
144
166
|
"additionalProperties": false,
|
|
145
167
|
"properties": {
|
|
146
168
|
"mode": { "type": "string", "enum": ["pinned", "vendored"] },
|
|
147
|
-
"ref": {
|
|
148
|
-
|
|
169
|
+
"ref": {
|
|
170
|
+
"type": "string",
|
|
171
|
+
"description": "Pinned mode: the git ref the runtime actions are referenced at. Omit it and the compiler uses its own release tag (v<version>), so the workflows and the actions they call always come from the same release. Name an exact tag or a commit to hold them elsewhere. Do not use v1: that tag has not moved since 0.1.2."
|
|
172
|
+
},
|
|
173
|
+
"owner_repo": { "type": "string" },
|
|
174
|
+
"runs_on": {
|
|
175
|
+
"type": "string",
|
|
176
|
+
"minLength": 1,
|
|
177
|
+
"description": "The runner label every generated job uses. Default ubuntu-latest. A node's runs_on= attribute overrides it for that node's jobs."
|
|
178
|
+
}
|
|
149
179
|
}
|
|
150
180
|
},
|
|
151
181
|
"personas": {
|
package/skill/SKILL.md
CHANGED
|
@@ -92,8 +92,17 @@ Listen for:
|
|
|
92
92
|
a `human-gate` is mandatory — it is a first-class node for exactly this reason. Give it an
|
|
93
93
|
out-edge to the merge gate (`human_gate -> merge_gate`): that is what turns the Environment
|
|
94
94
|
approval into a check the merge requires on that exact commit, instead of a lane running
|
|
95
|
-
beside the gate. Also confirm `identity.bot_login` —
|
|
96
|
-
|
|
95
|
+
beside the gate. Also confirm `identity.bot_login` — it must be the account the pipeline
|
|
96
|
+
actually posts as (under PAT auth, the PAT's owner). Verdict guards and the merge gate use
|
|
97
|
+
it to tell the reviewer's approval from a stranger's, and it is how the pipeline knows
|
|
98
|
+
which PRs it wrote.
|
|
99
|
+
- **People and agents share the repo** → ask two things and write them down. *Whose PRs
|
|
100
|
+
should the pipeline review, besides its own?* → the `rollout` block in
|
|
101
|
+
`foundry.config.yaml` (`authors: []` to start with only its own; add logins or an
|
|
102
|
+
`opt_in_label` to widen; `rollout: {}` for everyone). *Should it merge what it writes?* →
|
|
103
|
+
`merge="off"` (publish the gate's verdict as a check, a person merges — the default) or
|
|
104
|
+
`merge="agent-only"` on the gate. It never merges or pushes to a person's PR. See
|
|
105
|
+
"Hybrid harnesses" in `reference/node-types.md`.
|
|
97
106
|
- **Invariants** → `scope.yaml`'s `immutable_paths` (enforced three ways by the generated
|
|
98
107
|
output: a PR guard workflow, the pre-push strip, and the merge gate; agents can never modify —
|
|
99
108
|
e.g. `.github/workflows/`) and `forbidden_paths`/`forbidden_operations` (prompt-enforced).
|
|
@@ -46,7 +46,7 @@ outcome for an attribute meant to *restrict* a lane.
|
|
|
46
46
|
| `context=` | agent types | `issue` \| `pr-diff` \| `pr-review` \| `codebase` \| `none` |
|
|
47
47
|
| `output=` | `analyst` | `comment` \| `doc:<path-glob>` (docs-only write allowlist) |
|
|
48
48
|
| `title="Fletch"` | any job-emitting type | the workflow's `name:`, so a PR check reads `Fletch / reviewer` instead of `reviewer / reviewer`. Guard, select and mark jobs follow (`Fletch / reviewer guard`). Defaults to the node id (the older spelling `name=` still works). Changing it renames the check — update any branch-protection rule that names it |
|
|
49
|
-
| `harness_ref="head"` | `pr-review`, `pr-fix`, PR-context `analyst`, `fan_in` | opt **out** of the default. By default every lane handed a pull request reads its harness files — role, prompt, `scope.yaml`, `communication.md`, the `agent-setup` composite, and in vendored mode the runtime actions — from the PR's **base ref**, via a second sparse checkout into `.gp-foundry/harness/` (git-excluded, so a lane that commits never sweeps it in). The PR head stays the working tree. Read from the head, a branch cut before the harness merged has no role file, and a PR that edits `.github/agents/` is judged by its own edit, by an agent holding secrets. `"head"` restores the old behaviour for testing a harness change in its own PR; the validator warns |
|
|
49
|
+
| `harness_ref="head"` | `pr-review`, `pr-fix`, PR-context `analyst`, `fan_in` | opt **out** of the default. By default every lane handed a pull request reads its harness files — role, prompt, `scope.yaml`, `communication.md`, the `agent-setup` composite, and in vendored mode the runtime actions — from the PR's **base ref**, via a second sparse checkout into `.gp-foundry/harness/` (git-excluded, so a lane that commits never sweeps it in). The PR head stays the working tree. Read from the head, a branch cut before the harness merged has no role file, and a PR that edits `.github/agents/` is judged by its own edit, by an agent holding secrets. `"head"` restores the old behaviour for testing a harness change in its own PR; the validator warns. One automatic exception: when the base ref has **no harness at all** (the spec file is missing — the PR that installs the harness), the head's files are used, with a notice, so that PR is not dead at setup |
|
|
50
50
|
| `persist_credentials=true\|false` | `analyst`, `issue-agent`, `pr-review`, `fan_in` | whether the checkout leaves its token in `.git/config`. Default **false** on these read-and-advise lanes (they never push, and an agent with a shell can read it there) — except with `checkout="partial"`, whose on-demand blob fetches need it. `false` together with `checkout="partial"` is a build error. Lanes that push always keep it |
|
|
51
51
|
| `repo_guides=false` | agent types | stop the CLI auto-loading the repo's own `CLAUDE.md` / `AGENTS.md` into every turn (run-agent passes `--settings` with `claudeMdExcludes` for the workspace). The role, conventions and scope are then the agent's whole standing brief. Worth it when the repo guide is large: it is paid for on every turn |
|
|
52
52
|
| `gates="ci.yml, lint / eslint, e2e?90"` | `pr-review` | the CI the review depends on; each conclusion is put in front of the reviewer, and the job timeout grows to cover the waits. An entry ending in `.yml`/`.yaml` waits on that **workflow**; any other entry is a **check-run name** — the way to gate on one job of a larger workflow, or on a check Actions did not produce (external CI, a status app). Check-runs are read with `GITHUB_TOKEN` (the job gains `checks: read`), since a fine-grained PAT cannot hold the Checks permission. Options follow the name, each introduced by `?`: `?N` is the grace, in seconds, to wait for the target to *appear* before concluding `skipped` (default 90) — raise it for a slow-starting check, lower it for one that only runs on some heads; `?info` marks the gate **advisory** (a review bot, say): its result is listed for the reviewer under "Informational checks", where `skipped` is normal and a `failure` is input to weigh, instead of under the rule that anything but `success` blocks. They combine: `bugbot?info?30`. Names cannot contain a comma or `?` |
|
|
@@ -55,7 +55,7 @@ outcome for an attribute meant to *restrict* a lane.
|
|
|
55
55
|
| `opt_in_label="<key>"` | wherever `authors=` binds | widens the allowlist: the lane also runs on a PR that carries this label, whoever opened it (`authors=` ∪ label). The key resolves through `labels.<key>` in `foundry.config.yaml`, like `skip="label:<key>"` (used literally when unmapped). Compiles to an OR in the job-level `if:`, a `pull_request.labeled` trigger that admits only this label's event (other label events on an allowlisted PR do not start a run; the run GitHub still creates for them gets its own `<node>-noop-<run id>` concurrency group, so it cannot cancel or displace a review of that PR, while the opt-in label's own event joins the PR's group like a push), and the same OR in the `<node>_guard` job's fail-closed author check against the live PR (`OPT_IN_LABEL` env) and in a sweep's select job. `repo.branch_prefix` still applies. A fixer gets the `if:` widening but no `labeled` trigger. Needs an allowlist (`authors=` or `repo.authors`); without one `validate` errors (`node.opt-in-without-authors`) |
|
|
56
56
|
| `select="sweep"` | `pr-review` (with `schedule=`) | the **approver** pattern: instead of reacting to one PR's event, the lane runs on its cron and a `<node>_select` job deterministically picks the heads ready for a decision, then fans the lane out over them as a matrix. A head is selected when the PR is open, not a draft, on a `repo.branch_prefix` branch, **and** no review request is outstanding, **and** every check-run on the head is completed with no commit status pending (a head with **no** check-run at all waits until the PR has been quiet for 10 minutes, so a decision is never made in the gap before CI registers), **and** no verdict review by `identity.bot_login` exists on that exact head SHA, **and** the lane has not already delivered there. A **verdict** is a review whose last line, as a reader sees it, is **exactly** one of `**Verdict:** APPROVE`, `**Verdict:** REQUEST_CHANGES` or `**Verdict:** ESCALATE`: HTML comments are ignored (the harness appends its own after the verdict — the unchanged-diff stamp, the also-head marker), as are blank lines and leading or trailing whitespace. The marker anywhere else in the body (quoted, mid-sentence) does not count, and neither does a qualified line such as `**Verdict:** APPROVE (once gates pass)` — the merge gate would never read that as an approval, so a sweep that counted it as decided would leave the head stuck. The three words are `verdicts: [APPROVE, REQUEST_CHANGES, ESCALATE]` in `foundry.config.yaml` (approve, request changes, escalate, in that order); the select and mark jobs read them as `VERDICT_LINES`, and both merge-gate modes get them as the `verdicts` input and derive their markers from them (approval and escalation exact; rejection deliberately loose, `Verdict.*<word>`, since a missed rejection would let an earlier approval stand), so the sweep and the gate cannot disagree about what a verdict is. The merge gate reads review bodies the same way. Check-runs are read with `filter=all`, so every run counts, not just the newest per name. That last condition is the sweep's own record: after the lane succeeds on a head **and** the bot's verdict is on it, a `<node>_mark` job publishes the check-run `gp-foundry/swept (<node>)` on it (neutral, written with `GITHUB_TOKEN`). A successful run that posts **no** verdict is a holding state, not a decision: the role may have had nothing to decide yet (the head moved, a check was still running), so the head is not marked and not counted as a failure, and the next tick sweeps it again — up to **3** such runs per head. Each is recorded as a neutral `gp-foundry/sweep-idle (<node>)` check-run; on the third the mark job also publishes `gp-foundry/sweep-failed (<node>)` ("gave up after 3 runs without a verdict"), where a failed head shows, and the sweep stops selecting that head until a new commit is pushed, so a role that never posts a verdict (a shadow run, an abstention, a verdict in a shape the rule above does not recognize) costs three runs, not one every tick. A lane that fails leaves the head unmarked and is retried — up to **3** failed runs per head: each one is recorded as a neutral `gp-foundry/sweep-failed (<node>)` check-run, and after the third the sweep stops selecting that head until a new commit is pushed. A cancelled run is not counted. Oldest first, at most 10 per tick; a head whose state cannot be read is left for the next tick. "Concluded" is not "green" — a failed check is an answer the role must weigh — and a head with no checks at all counts as concluded. The lanes ahead of a sweep must post analyses, never `**Verdict:**`: the first verdict on a head is the decision. Requires `context="pr-diff"` or `"pr-review"` |
|
|
57
57
|
| `requires_review=true` | `select="sweep"` lanes | a head is a candidate only once a review by `identity.bot_login` covers it — submitted on the head (`commit_id`), or carrying the `<!-- gp-foundry:also-head:<node>:<head sha> -->` marker a guard adds when it skips that head as an unchanged diff — and that review is not itself a verdict (its last non-empty line does not start with `**Verdict:**`). For a sweep that acts on an upstream review: without it the lane starts a paid agent run on every tick for heads that are only waiting for that review. Checked in the select job's single reviews read (`REQUIRES_REVIEW` env); `validate` rejects it anywhere but a sweep |
|
|
58
|
-
| `post="review"` | `pr-review`, PR-context `analyst` (sweeps too) | the agent **prints** its review and a compiled `Post the review` step posts it with the lane's token; `run-agent` is given **no** `github-token`, whatever the role's `tools:` say (`validate` warns, `node.post-review-gh-tools`, when the role still lists gh: the post step posts; drop gh from tools). A shell under `--permission-mode dontAsk` denies the quoting a real review body needs (backticks, escaped quotes in a heredoc or `-f body=`), and an agent reading untrusted PR text should not hold a token anyway. **Output contract** (also appended to the prompt as its last section, `## Output`): the final message ends with one fenced code block tagged `json` holding one object, `{"body": "<markdown>", "comments": [{"path": "...", "line": N, "side": "RIGHT", "body": "..."}], "event": "COMMENT"}`. `comments` is optional (`[]` for none); `event` must be `COMMENT`; `commit_id` is set by the step to the head, never by the agent. The step takes the **last** such block from run-agent's captured stdout (`stdout-file` output), validates it (object, string `body`, each comment a string `path`, positive integer `line` and string `body`), prepends the heading line `PR #<n> head <sha>` (`post_marker=`) and POSTs `pulls/{n}/reviews`. No
|
|
58
|
+
| `post="review"` | `pr-review`, PR-context `analyst` (sweeps too) | the agent **prints** its review and a compiled `Post the review` step posts it with the lane's token; `run-agent` is given **no** `github-token`, whatever the role's `tools:` say (`validate` warns, `node.post-review-gh-tools`, when the role still lists gh: the post step posts; drop gh from tools). A shell under `--permission-mode dontAsk` denies the quoting a real review body needs (backticks, escaped quotes in a heredoc or `-f body=`), and an agent reading untrusted PR text should not hold a token anyway. **Output contract** (also appended to the prompt as its last section, `## Output`): the final message ends with one fenced code block tagged `json` holding one object, `{"body": "<markdown>", "comments": [{"path": "...", "line": N, "side": "RIGHT", "body": "..."}], "event": "COMMENT"}`. `comments` is optional (`[]` for none); `event` must be `COMMENT`; `commit_id` is set by the step to the head, never by the agent. The step takes the **last** such block from run-agent's captured stdout (`stdout-file` output), validates it (object, string `body`, each comment a string `path`, positive integer `line` and string `body`), prepends the heading line `PR #<n> head <sha>` (`post_marker=`) and POSTs `pulls/{n}/reviews`. With no fenced block it falls back to a bare object at the end of the output (the last line ending in `}`, back to the latest line beginning with `{` from which the rest parses as one object with a string `body`); a fenced block always wins. No review in either form, or a malformed one: nothing is posted and the step warns with the first 200 characters of the output. A 422 for an inline comment off the diff (GitHub does not say which): one retry with every inline finding moved into the body under "Findings on unchanged lines" (before the verdict line on a verdict lane). The step adds one line to the job summary under the agent's output: a link to the posted review, or a plain statement that nothing was posted and why. Idempotent, keyed on the lane: every review the step posts ends with a hidden marker, `<!-- gp-foundry:posted:<node>:<head sha> -->`, and a review by `identity.bot_login` on the head carrying this node's marker means the step posts nothing. So lanes can share a bot login and a heading — a reviewer's review does not stop an approver's verdict, nor the reverse — and a reviewer that posts a verdict of its own still recognizes it on a re-run. (A review posted before the marker existed is matched the old way, by its heading; on a verdict lane only if it is itself a verdict.) The marker is an HTML comment, which every verdict test ignores. On a sweep (`select="sweep"`) the review is the verdict: the body's last line must be one of the exact verdict lines, or nothing is posted. The diff stamp and the also-head marker work on the posted review |
|
|
59
59
|
| `post_marker="PR #<n> head <sha>"` | with `post="review"` | the heading the post step puts on the review's first line; `<n>` and `<sha>` are replaced. Single line. It is for the reader — idempotency is keyed on the hidden posted marker, so lanes posting as one bot may share a heading |
|
|
60
60
|
| `cancel_in_progress=true\|false` | agent types | whether a newer event for the same issue/PR **cancels** the run in flight rather than queueing behind it. Default `false` (`true` for `issue-agent`). Good for a reviewer — a review of a superseded head is waste. On a lane that writes code (producer, pr-fix, committing scheduled-agent) the validator warns: cancellation skips the commit/push salvage, so unpushed work is lost |
|
|
61
61
|
| `checkout="partial"` | any node that checks out | a blob-less clone with full history (`fetch-depth: 0` + `filter: blob:none`): every commit and tree, file contents on demand. `git log`, `git blame` and merge-base diffs work as in a full clone without paying for every version of every file — for big repos where the reviewer needs history |
|
|
@@ -64,14 +64,48 @@ outcome for an attribute meant to *restrict* a lane.
|
|
|
64
64
|
| `commit="none\|pr\|direct"` | `scheduled-agent` | how the lane persists output: `direct` (default) commits to base; `pr` opens a reviewed PR; `none` no commit/push (read-only lane) |
|
|
65
65
|
| `secrets="A,B"` | agent types | extra Actions secrets exposed to THIS lane's env (unioned with global `agent.secrets`); least-privilege scoping, e.g. a Sentry token only on the sweeper |
|
|
66
66
|
| `permissions="id-token: write"` | any job-emitting type | extra GitHub token scopes merged into the job's `permissions:` block (the attr wins on conflict); comma-separated `<scope>: read\|write\|none`. The generic opt-in for GitHub-native capabilities — e.g. `id-token: write` lets a consumer-owned setup step mint an OIDC token and federate into a cloud provider, with all provider specifics in consumer-owned composites |
|
|
67
|
+
| `runs_on="<label>"` | any job-emitting type | the runner label for this node's jobs (its guard, select and mark jobs follow). Default: `runtime.runs_on` in `foundry.config.yaml`, else `ubuntu-latest`. One plain label |
|
|
67
68
|
| `timeout=N` | agent types | job `timeout-minutes` (default 35 producer/pr-fix, 20 scheduled-agent). For lanes that run an agent with a salvage epilogue (producer, pr-fix, scheduled-agent) the agent's own step cap is derived as `N − 10`: the 10-min margin lets a cold-cache toolchain setup (~7 min) run and the commit/push/open-PR salvage finish within the job cap, so an over-running agent fails its STEP (salvage still runs) instead of being job-cancelled (#12545/#12611). Raise `N` to give the agent more working time; the margin stays 10 |
|
|
68
69
|
| `agent_attempts=N` | agent types | how many times run-agent invokes the CLI when it fails **transiently** (5xx, overloaded, dropped connection); default 3, backing off 15s and doubling. A real agent error and a usage-limit wall are never retried either way. Set `1` on a lane whose role has an **unconditional** side effect — e.g. the Herald posts a Slack digest with no dedup, so a retry after a partial run would post it twice. Roles that read current state first (the Sentry sweeper's `<!-- sentry:<id> -->` marker, the Supervisor skipping prior escalations) are safe to retry. Distinct from `max_attempts=` above |
|
|
69
70
|
| `policy="policy/merge.yaml"` | `merge-gate` | merge-policy file |
|
|
70
|
-
| `
|
|
71
|
+
| `merge="off\|agent-only"` | `merge-gate` | the **single gate**, for a repo where people and agents both open PRs. Every tick it judges every PR in scope against the policy and publishes the result as a check on the head (`check_name=`, default `gp-foundry/approval (<node>)`): `success` when ready, `failure` with the reason, `action_required` when escalated, `neutral` while awaiting the approver if the policy says so. `"off"` does only that. `"agent-only"` also acts on PRs the pipeline **wrote** — opened by `identity.bot_login` with every commit its own — merging them when ready and applying the policy's labels when not. A person's PR only ever gets the check, and the check says who merges. One commit by anyone else makes an agent PR human-merged. **Scope is the `rollout` block in `foundry.config.yaml`, not the branch prefix**: drafts and other bots' PRs never, the pipeline's own always, then the dial; per-node `authors=` / `opt_in_label=` / `skip=` are errors here. Under App auth the check is published with the harness's App token and only that App's runs are adopted, so another workflow's `GITHUB_TOKEN` cannot publish one that passes for it (the App needs **Checks: write**). Needs `identity.bot_login` for `"agent-only"`. A gate with neither `merge=` nor `mode=` is the original gate, unchanged: it merges approved PRs on a `repo.branch_prefix` branch and publishes no check |
|
|
72
|
+
| `mode="merge\|evaluate"` | `merge-gate` | **Older spelling, kept working; prefer `merge=`.** `merge` (default) merges the first qualifying PR or labels it. `evaluate` never merges, labels or comments: every tick it evaluates the policy for every open, non-draft PR on a `repo.branch_prefix` branch (narrowed by `authors=` / `repo.authors`, `opt_in_label=` and `skip="bot-author,label:<key>"` when set; `unchanged-diff` is rejected) and publishes one check run per head. Conclusion: `success` when the gate would merge; `action_required` when the trusted reviewer's latest verdict on the head is `**Verdict:** ESCALATE` (or the configured escalate word); `neutral` ("Awaiting the approver") instead of `failure` for a head the trusted approver has not yet approved, rejected or escalated, whatever else fails on it, when the policy sets `no_verdict_conclusion: neutral` (default `failure`), with every other failing clause listed in the summary; `failure` otherwise, with the gate's code and reason in the summary and the open threads, failing checks and pending review requests in the text. The run is updated in place (one current result per head) and not written at all when nothing changed, so a reply or resolve flips it on the next tick with no model spend, and it can be made a required check. The job runs on `GITHUB_TOKEN` alone (`checks: write`, `pull-requests: read`, `contents: read`, no App token); the gate leaves its own check out of the CI rollup, and `require_clean_rebase` is off unless the policy sets it. A graph may carry a merge gate and an evaluate gate side by side |
|
|
71
73
|
| `check_name="fletch/approval"` | `merge-gate` with `mode="evaluate"` | the check run it publishes; default `gp-foundry/approval (<node>)`. Two evaluate gates may not share one (`node.duplicate-check-name`); on a merge-mode gate it is an error (`node.check-name-without-evaluate`) |
|
|
72
74
|
| `schedule="*/30 * * * *"` | `merge-gate`, sweeps | cron cadence |
|
|
73
75
|
| `environment=NAME` | `human-gate` | GitHub Environment gating approval (**required** on human-gate) |
|
|
74
76
|
|
|
77
|
+
### Hybrid harnesses: people and agents in one repo
|
|
78
|
+
|
|
79
|
+
A harness is **hybrid** when `foundry.config.yaml` has a `rollout` block — even an empty
|
|
80
|
+
one. That key changes how every PR lane and the gate decide what to look at:
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
rollout: # `rollout: {}` = every PR
|
|
84
|
+
authors: [alice, bob] # human PRs by these people are in scope
|
|
85
|
+
opt_in_label: agent-review # ...or any PR carrying this label
|
|
86
|
+
skip_label: no-agent-review # never these
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- **Scope is the rollout, not the branch prefix.** In order: a draft never; a PR with the
|
|
90
|
+
skip label never; a PR `identity.bot_login` opened always; another bot only if named in
|
|
91
|
+
`authors`; then a listed author or the opt-in label. A block naming neither `authors` nor
|
|
92
|
+
`opt_in_label` admits everyone. Finish a rollout by emptying the block, not deleting it:
|
|
93
|
+
without the key the harness is not hybrid.
|
|
94
|
+
- **One implementation.** Each event-driven PR lane gets a `<node>_guard` job that runs the
|
|
95
|
+
`pr-scope` action against the live PR; a sweep's select job asks the same action for its
|
|
96
|
+
candidates; the gate (`merge=`) uses the same rule. The job-level `if:` is only a cheap
|
|
97
|
+
prefilter on the event.
|
|
98
|
+
- **Lanes read or write.** `pr-review` and PR-context `analyst` lanes read: they run on any
|
|
99
|
+
PR in scope. `pr-fix` writes: it runs only on a PR the pipeline wrote — opened by the bot,
|
|
100
|
+
every commit its own. No lane pushes to a person's PR.
|
|
101
|
+
- **Per-node scope is an error here**: `authors=`, `opt_in_label=`, `skip=` (other than
|
|
102
|
+
`unchanged-diff`, which is a lane's own behaviour) and `repo.authors`. Lanes always listen
|
|
103
|
+
for `ready_for_review`, and for `labeled` when there is an opt-in label.
|
|
104
|
+
- Needs `identity.bot_login` wherever a writing lane or `merge="agent-only"` is used.
|
|
105
|
+
|
|
106
|
+
Without a `rollout` key nothing here applies: lanes are scoped by `repo.branch_prefix` and
|
|
107
|
+
the per-node attributes below, exactly as before.
|
|
108
|
+
|
|
75
109
|
### What each lane's credentials can do
|
|
76
110
|
|
|
77
111
|
- **App token (`auth.mode: app`)** is minted per job with `permission-*` inputs, so it carries
|
|
@@ -134,7 +168,7 @@ digraph harness {
|
|
|
134
168
|
builder [type=producer, role="roles/builder.md", context=issue]
|
|
135
169
|
reviewer [type=pr-review, role="roles/reviewer.md", context="pr-diff", gates="ci.yml"]
|
|
136
170
|
fixer [type=pr-fix, role="roles/fixer.md", max_attempts=3]
|
|
137
|
-
merge_gate [type=merge-gate, policy="policy/merge.yaml", schedule="*/30 * * * *"]
|
|
171
|
+
merge_gate [type=merge-gate, policy="policy/merge.yaml", schedule="*/30 * * * *", merge="off"]
|
|
138
172
|
needs_human [type=exit]
|
|
139
173
|
|
|
140
174
|
start -> scout [on="issues.opened"]
|
|
@@ -21,6 +21,10 @@ auth: # how the harness authenticates to GitHub for writes
|
|
|
21
21
|
token_secret: AGENT_PAT # gh secret set AGENT_PAT --body <fine-grained-pat>
|
|
22
22
|
|
|
23
23
|
identity: # git author for the agent's commits/PRs
|
|
24
|
+
# bot_login MUST be the account the pipeline actually posts as: under `pat` auth the
|
|
25
|
+
# PAT's owner, under `app` auth `<app-slug>[bot]`. It is how the pipeline recognizes the
|
|
26
|
+
# PRs it wrote (the only ones the fixer pushes to and the gate may merge) and its own
|
|
27
|
+
# reviews. If it is wrong, the pipeline ignores its own work.
|
|
24
28
|
bot_login: agent-bot
|
|
25
29
|
git_name: Agent Bot
|
|
26
30
|
git_email: agent-bot@users.noreply.github.com
|
|
@@ -35,7 +39,20 @@ agent: # the coding-agent CLI + default model
|
|
|
35
39
|
repo:
|
|
36
40
|
base_branch: main
|
|
37
41
|
branch_prefix: agent/ # branches look like agent/<issue>-slug (matches policy branch_prefix)
|
|
38
|
-
|
|
42
|
+
|
|
43
|
+
# Which pull requests the pipeline looks at. Its OWN (opened by identity.bot_login) are
|
|
44
|
+
# always in scope; this dial is for bringing it to people's PRs gradually. Drafts and
|
|
45
|
+
# other bots' PRs are never in scope.
|
|
46
|
+
# authors: [] nobody's PRs but the pipeline's own (the starting point)
|
|
47
|
+
# authors: [alice, bob] ...and these people's
|
|
48
|
+
# opt_in_label: <label> ...and any PR carrying this label
|
|
49
|
+
# skip_label: <label> never a PR carrying this one
|
|
50
|
+
# rollout: {} every PR — the end of a rollout. Keep the key: it is what makes
|
|
51
|
+
# the reviewer, the fixer and the gate share one scope.
|
|
52
|
+
rollout:
|
|
53
|
+
authors: []
|
|
54
|
+
# opt_in_label: agent-review
|
|
55
|
+
# skip_label: no-agent-review
|
|
39
56
|
|
|
40
57
|
labels: # semantic key -> actual repo label. Guards (`when="label=build"`) resolve
|
|
41
58
|
# through this map, so renaming a repo label is a one-line change HERE —
|
|
@@ -48,7 +65,9 @@ labels: # semantic key -> actual repo label. Guards (`when="label=build"`) resol
|
|
|
48
65
|
# agents/policy/merge.yaml — the merge-gate reads THAT file at runtime, not this one.
|
|
49
66
|
|
|
50
67
|
runtime: # how generated workflows reference the runtime-core actions
|
|
68
|
+
# runs_on: ubuntu-latest # the runner label for every generated job (a node's runs_on= overrides it)
|
|
51
69
|
# vendored — `gp-foundry vendor` copies the actions into .github/actions/ (default;
|
|
52
70
|
# self-contained, no external dependency, upgrade by re-running vendor).
|
|
53
|
-
# pinned — reference <owner_repo>/actions/<name>@<ref> centrally
|
|
71
|
+
# pinned — reference <owner_repo>/actions/<name>@<ref> centrally. With no `ref:` the
|
|
72
|
+
# compiler uses its own release tag, so rebuilding upgrades both together.
|
|
54
73
|
mode: vendored
|
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
// `when=` GitHub-observable guard. Compile with `gp-foundry build`. NEVER hand-edit the
|
|
5
5
|
// generated .github/workflows/*.yml — edit this graph and rebuild.
|
|
6
6
|
//
|
|
7
|
-
// This default graph is a complete "dark factory": issues in → reviewed,
|
|
8
|
-
//
|
|
9
|
-
//
|
|
7
|
+
// This default graph is a complete "dark factory": issues in → reviewed PRs out, with
|
|
8
|
+
// self-healing (janitor + supervisor) and self-improving (retro) lanes. It starts with
|
|
9
|
+
// merging OFF: the gate publishes its verdict as a check on each PR and a person merges.
|
|
10
|
+
// Set merge="agent-only" on the gate when you want the PRs the pipeline wrote merged for
|
|
11
|
+
// you. Every cycle MUST keep a bounded escape edge to an `exit` node.
|
|
10
12
|
|
|
11
13
|
digraph harness {
|
|
12
14
|
// ── nodes ─────────────────────────────────────────────────────────────────
|
|
@@ -28,8 +30,10 @@ digraph harness {
|
|
|
28
30
|
// bounded fix loop with the reviewer
|
|
29
31
|
fixer [type=pr-fix, role="agents/roles/fixer.md", max_attempts=3]
|
|
30
32
|
|
|
31
|
-
//
|
|
32
|
-
|
|
33
|
+
// the gate: judges every PR in scope against the merge policy and publishes the result
|
|
34
|
+
// as a check. merge="off" never merges; merge="agent-only" also merges the PRs the
|
|
35
|
+
// pipeline wrote (opened by the bot, every commit its own). A person's PR is never merged.
|
|
36
|
+
merge_gate [type=merge-gate, policy="agents/policy/merge.yaml", schedule="*/30 * * * *", merge="off"]
|
|
33
37
|
|
|
34
38
|
// self-healing: rebase conflicted PRs; re-drive stranded issues/PRs
|
|
35
39
|
janitor [type=scheduled-agent, role="agents/roles/janitor.md", schedule="*/30 * * * *"]
|
|
@@ -85,14 +85,25 @@ labels:
|
|
|
85
85
|
# bot_logins: ["greptile-apps[bot]", "cursor[bot]"]
|
|
86
86
|
# bot_thread_blocking_regex: "P1|High Severity"
|
|
87
87
|
#
|
|
88
|
-
# What the check says for a head
|
|
89
|
-
#
|
|
90
|
-
# red X off every PR
|
|
88
|
+
# What the check says for a head the approver has not given a verdict on yet (no
|
|
89
|
+
# approve, reject or escalate): failure (default) or neutral ("Awaiting the approver"),
|
|
90
|
+
# which keeps a red X off every PR the approver has not decided. The neutral summary
|
|
91
|
+
# still lists every other failing clause (CI, threads, review requests, size).
|
|
91
92
|
# no_verdict_conclusion: neutral
|
|
92
93
|
#
|
|
93
94
|
# Fail (`review-requested`) while a reviewer or team is still requested.
|
|
94
95
|
# require_no_review_requests: true
|
|
95
96
|
#
|
|
97
|
+
# Fail (`changes-requested`) while any PERSON's review stands at "changes requested".
|
|
98
|
+
# Without it the latest verdict wins, so a later approval from the bot overrides a
|
|
99
|
+
# teammate's block; with it the block holds until they approve or it is dismissed.
|
|
100
|
+
# require_no_human_changes_requested: true
|
|
101
|
+
#
|
|
102
|
+
# Labels that hand a PR to a person outright: never merged, and in evaluate mode the
|
|
103
|
+
# check is `action_required`, whether or not the approver has given a verdict.
|
|
104
|
+
# (`blocking_labels` only hold a merge back; these say who decides.)
|
|
105
|
+
# escalation_labels: [needs-human-decision]
|
|
106
|
+
#
|
|
96
107
|
# The trusted reviewer's latest verdict on the head being an escalation turns the check
|
|
97
108
|
# `action_required` (a human decides). Defaults to the exact `**Verdict:** ESCALATE`
|
|
98
109
|
# line; this key only overrides it.
|