@thegpvc/gp-foundry 0.1.1 → 0.2.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.
@@ -15,11 +15,19 @@ repository layout is hardcoded. Everything is driven by inputs and a scope file.
15
15
  YAML file (`scope-path`, default `.github/agents/scope.yaml`) using a
16
16
  dependency-free `awk` scan. If the file or the key is missing, it defaults to
17
17
  `.github/workflows/`.
18
- 2. **Strip protected path changes.** Reverts any changes to the immutable paths —
19
- both committed (via `git checkout <base> -- <file>` / `git rm`, amended into
20
- the tip commit) and uncommitted (working tree + index). This prevents pushes
21
- from being rejected when the token lacks permission for those paths (e.g. the
22
- GitHub `workflows` permission).
18
+ 2. **Strip protected path changes.** Restores every immutable path to its exact
19
+ base-branch content, whichever way the agent got the edit in: committed on the
20
+ branch, staged, left in the working tree, or an invented (untracked) file.
21
+ Files present in base are restored with `git checkout <base> -- <file>`; files
22
+ absent from base are untracked and deleted. Restorations are folded into the
23
+ tip commit (and if that empties it — the illegal edit *was* the commit — the
24
+ commit is dropped). This prevents pushes from being rejected when the token
25
+ lacks permission for those paths (e.g. the GitHub `workflows` permission).
26
+
27
+ Note what this deliberately does not do: it repairs the tip, not history. If
28
+ an *earlier* commit on the branch touched a path the token cannot push, the
29
+ push is still rejected — the strip is a safety net for the common case, not a
30
+ history rewriter.
23
31
  3. **Commit uncommitted changes.** If the working tree is dirty, stages
24
32
  everything and commits with `commit-message` (or a generated default using
25
33
  `agent-name`).
@@ -21,6 +21,14 @@ inputs:
21
21
  push workflow changes). If the file or the key is absent, defaults to
22
22
  `.github/workflows/`.
23
23
  default: .github/agents/scope.yaml
24
+ allowed-paths:
25
+ description: >-
26
+ Optional newline- or comma-separated allowlist of path prefixes this lane
27
+ may write. When set, changes anywhere else are reverted before the push —
28
+ the inverse of `immutable_paths`, for a lane whose remit is narrow (a
29
+ scheduled agent that may only write its memory directory, say). Empty means
30
+ "anywhere the immutable paths don't forbid".
31
+ default: ""
24
32
  commit-message:
25
33
  description: Fallback commit message (if the agent left uncommitted changes).
26
34
  default: ""
@@ -90,33 +98,90 @@ runs:
90
98
  env:
91
99
  BASE_BRANCH: ${{ inputs.base-branch }}
92
100
  IMMUTABLE_PATHS: ${{ steps.immutable.outputs.paths }}
101
+ ALLOWED_PATHS: ${{ inputs.allowed-paths }}
93
102
  run: |
94
103
  # Revert any changes to immutable paths — the restricted App token
95
104
  # typically lacks permission to push them (e.g. `workflows`), so the
96
- # push would be rejected. Strip from committed and uncommitted changes.
105
+ # push would be rejected. The rule is one sentence: under an immutable
106
+ # path, the tree must match the base branch EXACTLY — no matter whether
107
+ # the agent committed the edit, staged it, or left it in the worktree.
108
+ #
109
+ # Restoring from the base (not from HEAD or the index) is what makes the
110
+ # three cases collapse into one. `git checkout -- <path>` is deliberately
111
+ # NOT used anywhere here: it rewrites the worktree from the INDEX, so it
112
+ # reinstates the very staged edit this step exists to drop.
97
113
  BASE_REF="origin/${BASE_BRANCH}"
98
114
 
115
+ # Everything that differs from base under a pathspec: committed on this
116
+ # branch, staged/unstaged against HEAD, or a brand-new untracked file.
117
+ changed_under() {
118
+ {
119
+ git diff --name-only "${BASE_REF}...HEAD" -- "$1" 2>/dev/null || true
120
+ git diff --name-only HEAD -- "$1" 2>/dev/null || true
121
+ git ls-files --others --exclude-standard -- "$1" 2>/dev/null || true
122
+ } | sort -u
123
+ }
124
+
125
+ # Put one file back the way base has it (deleting it if base never had it).
126
+ restore_from_base() {
127
+ if git cat-file -e "${BASE_REF}:${1}" 2>/dev/null; then
128
+ git checkout "$BASE_REF" -- "$1" 2>/dev/null || true
129
+ else
130
+ git rm -q -f --ignore-unmatch --cached -- "$1" >/dev/null 2>&1 || true
131
+ rm -f -- "$1"
132
+ fi
133
+ }
134
+
99
135
  while IFS= read -r P; do
100
136
  [ -z "$P" ] && continue
101
137
 
102
- # 1. Committed changes (agent may have committed via git).
103
- CHANGED=$(git diff --name-only "${BASE_REF}...HEAD" -- "$P" 2>/dev/null || true)
104
- if [ -n "$CHANGED" ]; then
105
- echo "::warning::Agent committed changes to protected path '$P' — stripping"
106
- echo "$CHANGED"
107
- while IFS= read -r f; do
108
- [ -z "$f" ] && continue
109
- git checkout "$BASE_REF" -- "$f" 2>/dev/null || git rm -f "$f" 2>/dev/null || true
110
- done <<< "$CHANGED"
111
- fi
138
+ CHANGED=$(changed_under "$P")
139
+ [ -z "$CHANGED" ] && continue
112
140
 
113
- # 2. Uncommitted changes (working tree / staged).
114
- git checkout -- "$P" 2>/dev/null || true
115
- git reset -- "$P" 2>/dev/null || true
141
+ echo "::warning::Agent modified protected path '$P' — stripping"
142
+ echo "$CHANGED"
143
+
144
+ while IFS= read -r f; do
145
+ [ -z "$f" ] && continue
146
+ restore_from_base "$f"
147
+ done <<< "$CHANGED"
116
148
  done <<< "$IMMUTABLE_PATHS"
117
149
 
118
- # Fold any restorations staged above into the tip commit.
119
- git diff --staged --quiet || git commit --amend --no-edit
150
+ # Optional allowlist: this lane may only write these prefixes, so revert
151
+ # everything else. Immutable paths above are the floor no lane may cross;
152
+ # this is the ceiling a narrow lane opts into.
153
+ if [ -n "$ALLOWED_PATHS" ]; then
154
+ ALLOWED=$(printf '%s' "$ALLOWED_PATHS" | tr ',' '\n' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | grep -v '^$' || true)
155
+ while IFS= read -r f; do
156
+ [ -z "$f" ] && continue
157
+ KEEP=""
158
+ while IFS= read -r A; do
159
+ [ -z "$A" ] && continue
160
+ case "$f" in
161
+ "$A"|"$A"/*) KEEP=1; break ;;
162
+ *) case "$A" in */) case "$f" in "$A"*) KEEP=1; break ;; esac ;; esac ;;
163
+ esac
164
+ done <<< "$ALLOWED"
165
+ if [ -z "$KEEP" ]; then
166
+ echo "::warning::Change to '$f' is outside this lane's allowed paths — reverting"
167
+ restore_from_base "$f"
168
+ fi
169
+ done <<< "$(changed_under '.')"
170
+ fi
171
+
172
+ # Fold the restorations into the branch's tip commit — but only when there
173
+ # IS a commit of our own to amend. With nothing ahead of base, `--amend`
174
+ # would rewrite the base commit itself.
175
+ if ! git diff --staged --quiet; then
176
+ if [ "$(git rev-list "${BASE_REF}..HEAD" --count 2>/dev/null || echo 0)" -gt 0 ]; then
177
+ # Amending fails when the restoration empties the tip commit — i.e. the
178
+ # illegal edit WAS the whole commit. Drop that commit instead; anything
179
+ # else the agent left behind is committed by the next step.
180
+ git commit --amend --no-edit || git reset --soft HEAD~1
181
+ else
182
+ git commit -m "chore: strip edits to immutable paths"
183
+ fi
184
+ fi
120
185
 
121
186
  - name: Commit uncommitted changes
122
187
  shell: bash
@@ -19,23 +19,61 @@ disqualifying first:
19
19
  1. **Blocking labels** — PR carries any `blockingLabels` (e.g. `needs-human`,
20
20
  `rebase-needed`) → `skip`.
21
21
  2. **Branch prefix** — head branch must start with `branchPrefix` (if set).
22
- 3. **Bot-approval present** — `approvedAt` must be set (the wrapper derives it
23
- from an `APPROVED` review, or a `COMMENTED` review whose body matches
24
- `approvalBodyRegex`).
22
+ 3. **Approval present and trusted** — `approvedAt` must be set (the wrapper
23
+ derives it from an `APPROVED` review, or a `COMMENTED` review whose body
24
+ matches `approvalBodyRegex`). See [Who can approve](#who-can-approve).
25
25
  4. **Approval delay** — at least `approvalDelayMinutes` must have elapsed.
26
26
  5. **CI passing** — the check-run rollup for the head SHA must be `passing`
27
27
  (unless `requireCi: false`).
28
- 6. **Hand-written additions** — additions of non-`excludeGlobs` files must be
28
+ 6. **Required checks** — every entry in `requiredChecks` must have reported on
29
+ the head SHA with conclusion `success`. A check that never ran blocks the
30
+ merge; the CI rollup above cannot do that, since it only judges the checks
31
+ that happen to exist.
32
+
33
+ An entry may pin the **author** as well as the name, as `<name>@<app-slug>`.
34
+ Do that for any check that stands in for a human decision: a check-run's name
35
+ is public, so without the pin anything able to write checks — including the
36
+ App installation token every agent lane carries, which a job's `permissions:`
37
+ block does *not* constrain — can publish its own approval. `gp-foundry build`
38
+ emits the human-gate's check pinned to `@github-actions`, the app GITHUB_TOKEN
39
+ writes as. Leave third-party CI checks unpinned.
40
+ 7. **Hand-written additions** — additions of non-`excludeGlobs` files must be
29
41
  `<= maxAdditions`, else apply `labels.needsHuman`.
30
- 7. **Protected paths** — no changed file may match `protectedPaths`, else apply
42
+ 8. **Protected paths** — no changed file may match `protectedPaths`, else apply
31
43
  `labels.needsHuman`.
32
- 8. **Clean rebase** — the branch must rebase cleanly onto the base branch
44
+ 9. **Clean rebase** — the branch must rebase cleanly onto the base branch
33
45
  (unless `requireCleanRebase: false`), else apply `labels.rebaseNeeded`.
34
46
 
35
- If all pass, the action is `merge`.
47
+ If all pass, the action is `merge` — of the **exact head SHA that was scored**,
48
+ passed to GitHub as the merge's `sha` guard. If the head moved in between (the
49
+ janitor's rebase sweep runs on the same cadence as this poller), GitHub rejects
50
+ the call, the PR is labeled for a rebase, and the next poll re-scores the new
51
+ head. The gate never merges a commit it did not evaluate.
36
52
 
37
53
  Outcomes: `merge` (merge it), `label` (apply `label` and stop), `skip` (no-op).
38
54
 
55
+ ## Who can approve
56
+
57
+ An approval is an instruction to push code to the base branch, so the gate only
58
+ counts verdicts it can attribute:
59
+
60
+ - **Formal reviews** by the bot (`botLogin` / the `bot-login` input), or by an
61
+ author whose `author_association` is in `trustedAuthorAssociations` (default
62
+ `OWNER`, `MEMBER`, `COLLABORATOR` — i.e. write access). A review approval is
63
+ additionally bound to the head SHA: approve, then push, and the approval no
64
+ longer counts.
65
+ - **Plain issue comments** are not an approval channel unless
66
+ `allowCommentApprovals: true`. Even then they must come from a trusted author,
67
+ and because a comment carries no SHA the only binding available is that it
68
+ postdates the head commit — weaker than a review. Prefer leaving it off.
69
+ - **Rejections** (`CHANGES_REQUESTED`, or a body matching `rejectionBodyRegex`)
70
+ are counted from any formal review regardless of author: a rejection can only
71
+ ever hold a merge back, so accepting more of them is the safe direction. The
72
+ comment channel is on or off as a whole, so a drive-by comment cannot stall
73
+ the factory when comment approvals are disabled.
74
+
75
+ The latest verdict wins: a newer rejection invalidates an earlier approval.
76
+
39
77
  ## Inputs
40
78
 
41
79
  | input | required | description |
@@ -43,6 +81,8 @@ Outcomes: `merge` (merge it), `label` (apply `label` and stop), `skip` (no-op).
43
81
  | `pr-number` | yes | PR to evaluate. |
44
82
  | `token` | yes | Token with `contents:write` + `pull-requests:write` (use an App installation token so merges are attributed to the bot). |
45
83
  | `policy-path` | yes | Path to the policy file (YAML or JSON). |
84
+ | `bot-login` | no | Login of the reviewer bot whose verdicts are trusted; overrides the policy's `bot_login`. |
85
+ | `required-checks` | no | Comma/newline-separated check-run names that must be present and green on the head SHA; overrides the policy's `required_checks`. |
46
86
  | `clean-rebase`| no | Override the rebase check with `"true"`/`"false"`; inferred from mergeable state otherwise. |
47
87
  | `dry-run` | no | `"true"` to evaluate + emit outputs without mutating. |
48
88
 
@@ -73,10 +113,18 @@ blockingLabels:
73
113
  - "rebase-needed"
74
114
  requireCi: true
75
115
  requireCleanRebase: true
116
+ requiredChecks: # must be PRESENT and green on the head SHA
117
+ - "gp-foundry/human-approval (production)@github-actions" # @app pins the author
118
+ - "ci/build" # unpinned: any author
76
119
  labels:
77
120
  needsHuman: "needs-human"
78
121
  rebaseNeeded: "rebase-needed"
79
122
 
123
+ # who may approve (see "Who can approve"):
124
+ botLogin: "my-agent[bot]"
125
+ trustedAuthorAssociations: ["OWNER", "MEMBER", "COLLABORATOR"]
126
+ allowCommentApprovals: false # plain issue comments are NOT approvals
127
+
80
128
  # wrapper-only (I/O) knobs:
81
129
  approvalBodyRegex: "Verdict.*APPROVE" # count a COMMENTED review as approval
82
130
  ciIgnoreCheckNames: ["review", "fix", "sweep", "merge"]
@@ -30,6 +30,33 @@ inputs:
30
30
  Overrides the policy file's branchPrefix when set.
31
31
  required: false
32
32
  default: ""
33
+ checks-token:
34
+ description: >
35
+ Token used ONLY to read the check-runs rollup for the head SHA. That read
36
+ needs the Checks permission, which is a GitHub App permission — a
37
+ fine-grained PAT cannot be granted it, so passing the harness PAT here 403s
38
+ and the gate merges nothing. Pass ${{ github.token }} (an App installation
39
+ token) and give the job `permissions: checks: read`. Defaults to `token`,
40
+ which is correct only when that token is a GitHub App installation token.
41
+ required: false
42
+ default: ""
43
+ bot-login:
44
+ description: >
45
+ Login of the reviewer bot whose verdicts this gate trusts. Overrides the
46
+ policy file's bot_login. Verdicts from anyone else count only when their
47
+ author_association is in the policy's trusted_author_associations
48
+ (default: OWNER, MEMBER, COLLABORATOR).
49
+ required: false
50
+ default: ""
51
+ required-checks:
52
+ description: >
53
+ Comma- or newline-separated check-run names that must be PRESENT and
54
+ successful on the head SHA before merging. Unlike the CI rollup, a check
55
+ that never reported blocks the merge — this is how an Environment approval
56
+ job becomes a real precondition. Overrides the policy file's
57
+ required_checks.
58
+ required: false
59
+ default: ""
33
60
  clean-rebase:
34
61
  description: >
35
62
  Optional override for the clean-rebase check: "true" or "false". When