@vaultcompass/conductor 0.18.1 → 0.19.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 CHANGED
@@ -48,11 +48,18 @@ The hook runs every enabled gate on each commit and, when the commit is
48
48
  clean, prints one summary line, plus one status line per gate on stderr.
49
49
  Each gate can also be installed and run on its own.
50
50
 
51
- Then the same gates on every pull request, as one pinned workflow:
51
+ Then the same gates on every pull request, a lighter run on each push to
52
+ main, and a full scan every day, as one pinned workflow:
52
53
 
53
54
  ```yaml
54
55
  name: guardrails
55
- on: [pull_request, push]
56
+ on:
57
+ pull_request:
58
+ push:
59
+ branches: [main]
60
+ schedule:
61
+ - cron: '17 4 * * *'
62
+ workflow_dispatch:
56
63
  permissions:
57
64
  contents: read
58
65
  security-events: write
@@ -76,7 +83,9 @@ jobs:
76
83
  echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
84
  chmod +x "$bin/osv-scanner"
78
85
  echo "$bin" >> "$GITHUB_PATH"
79
- - uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
86
+ - uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
87
+ with:
88
+ stage: ${{ github.event_name == 'push' && 'push' || 'ci' }}
80
89
  - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
81
90
  if: always()
82
91
  with:
@@ -89,8 +98,41 @@ needed when the policy enables the secrets-history and vulnerabilities gates,
89
98
  and it pins both by version and checksum. On a pull request every gate reads
90
99
  its rules from the base branch, so a change cannot turn off the check that
91
100
  exists to catch it. The first pull request under a new policy cannot be judged
92
- by that policy, so read the careful path below before you make the check
93
- required.
101
+ by that policy: into the default branch it is reported as a proposal, exit 0
102
+ with nothing enforced, so read the careful path below before you make the
103
+ check required.
104
+
105
+ What each trigger runs. A pull request runs every gate at stage `ci`, and the
106
+ history scan reads only that pull request's own range, so a pull request is
107
+ judged on what it changes. A push to main runs at stage `push`: the
108
+ dependencies and secrets gates over the tree, and not the history scan or
109
+ osv-scanner, which are named as deferred in the report. The daily schedule
110
+ and a manual run have no base, so they run at stage `ci` over the whole of git
111
+ history and every tracked lockfile. The `fetch-depth: 0` above is what makes
112
+ that history scan possible: a shallow checkout makes the history gate
113
+ could-not-run on a pull request or a scheduled run alike, and exit 2 when the
114
+ gate is enforced (on a pull request it is always enforced).
115
+
116
+ What this gives up. A secret pushed straight to main with no pull request, and
117
+ a new advisory against a dependency already on main, are seen at the next
118
+ scheduled run, up to a day later, rather than on the push. Every change that
119
+ goes through a pull request is still fully judged.
120
+
121
+ Expect the scheduled run to be red at first. It judges the history and the
122
+ lockfiles as they stand, including what was there before conductor, and every
123
+ finding blocks. When it blocks, the report says how many of the findings
124
+ predate the policy file and lists each tool's own ignore file as the way to
125
+ record a reviewed one; see "Adoption ramp" below. A scheduled run is not a
126
+ required check, and a red one is the backlog, shown honestly. GitHub disables
127
+ scheduled workflows in a public repository after a period without repository
128
+ activity, and a failing scheduled run notifies whoever last edited the
129
+ schedule, so check that the schedule is still running.
130
+
131
+ The expression that picks the stage (`github.event_name == 'push' && 'push' ||
132
+ 'ci'`) is standard Actions syntax but has not been run on a real runner for
133
+ this recipe. Check that the first push run's report lists secrets-history and
134
+ vulnerabilities as deferred, and that the first scheduled run does not, before
135
+ you rely on it.
94
136
 
95
137
  ## Part of the Vault & Compass guardrails
96
138
 
@@ -191,6 +233,15 @@ required.
191
233
  stage is `commit`. A CI-only adopter that never runs conductor locally can
192
234
  stop at the first `conductor init`, with no hook at all.
193
235
 
236
+ The first run with no base (a local `conductor run`, a push, a scheduled
237
+ run) judges all of git history and every tracked lockfile, so on a
238
+ repository with history it can block on findings that were there before
239
+ conductor. It still exits 1 and every finding still blocks; when the
240
+ history or vulnerabilities gate blocks, the report adds an "existing
241
+ findings" section saying how many predate the policy file, how many are in
242
+ files that are gone, and what to do. A pull request is judged only on its
243
+ own change.
244
+
194
245
  **`.git/hooks` is never part of a clone**, so a hook one checkout has does
195
246
  not follow a teammate's clone, or a fresh clone of your own: hooks are per
196
247
  clone and per machine. Each clone that wants the hook runs
@@ -239,6 +290,11 @@ required.
239
290
  ```
240
291
  conductor 0.18.1
241
292
  verdict-token: blocked (1)
293
+ gate dependencies (dep-guard 0.20.0): ran, exit 0, 0 blocking
294
+ gate secrets (vault-guard 1.13.3): ran, exit 1, 1 blocking
295
+ gate intent (intent-guard): skipped (deferred to stage ci)
296
+ findings: 1 (1 blocking):
297
+ finding: BLOCKING vault-guard vault-guard/anthropic jest.config.mjs:14: Possible secret of type 'anthropic'
242
298
  conductor run: 2 gate(s), 1 finding(s)
243
299
 
244
300
  dependencies dep-guard 0.20.0 exit 0 153ms via dep-guard on path
@@ -256,6 +312,11 @@ required.
256
312
  verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
257
313
  ```
258
314
 
315
+ The lines under the verdict token are the report's head: one line per
316
+ gate (ran, did not run, skipped or disabled), then how many findings
317
+ there are and the first ten that block, by name. The sections under them
318
+ carry the detail, and every finding that does not block.
319
+
259
320
  The `mode`, `corpusBuiltAt`, `lockfileFormat`, `online`, `lookups` and
260
321
  `skipped-by-deadline` line under
261
322
  `dependencies`, and the `filesScanned`/`patternsActive` line under
@@ -289,15 +350,18 @@ required.
289
350
  and the workflow together, with `advisory: true` and `pr-comment: true`
290
351
  on the conductor step (the recipe under "Running the gates as an
291
352
  advisory check" below is a complete copy-paste job), and leave the check
292
- out of branch protection for this one pull request. The step still exits
293
- 2 on this pull request even with `advisory: true`: the base branch has no
294
- policy yet, so the run has no rules, and `advisory` never touches that
295
- exit code, only a blocking finding's. Leaving the check out of branch
296
- protection is what keeps that expected exit 2 from blocking the merge;
297
- the step posts a comment saying so with the remedy on it, which is the
298
- honest report of an unfinished adoption, not a broken tool. The same
299
- refusal recurs once on every new base branch; see "Why the first pull
300
- request still exits 2 under `advisory: true`" below.
353
+ out of branch protection for this one pull request. Into the default
354
+ branch, this pull request is reported as a **proposal**: the base branch
355
+ has no policy yet, so nothing can be enforced, and conductor runs the
356
+ policy the pull request adds and says what it would do. The step exits 0,
357
+ the verdict is `proposal (N)`, never `pass`, and the summary and the
358
+ comment say that nothing was enforced and how many findings would block
359
+ once the policy is merged. A green check on this one pull request means
360
+ the gates the new policy enforces could all run, and nothing more. The
361
+ step exits 2 when one of them could not run (a scanner that is not
362
+ installed, say), which is the fault to fix before merging, and it exits 2
363
+ when the pull request is not a first adoption; see "What the first pull
364
+ request reports" below.
301
365
 
302
366
  3. **Merge.** Every pull request after that is judged by the policy on the
303
367
  base branch, and a change to that policy shows up as a proposal line and
@@ -311,9 +375,10 @@ required.
311
375
  job into the one required check.
312
376
 
313
377
  There is deliberately no mode in which the pull request's own policy file
314
- decides the run, not even as a preview: step 1's preview gives you the same
315
- report without putting a file the pull request controls behind a verdict on
316
- the pull request page.
378
+ decides a verdict. The proposal in step 2 is the one run that reads it, and
379
+ it takes three keys from it (`enabled`, `stage`, `enforce`), enforces
380
+ nothing, and is labelled a proposal on every surface; once the base branch
381
+ has a policy, every rule comes from the base.
317
382
 
318
383
  ## Adoption ramp
319
384
 
@@ -348,7 +413,15 @@ first pull request gets switched off. The order that works:
348
413
 
349
414
  conductor reads `.gitleaksignore` from the base branch on a pull request,
350
415
  so adding the line takes effect after its own merge, like any other
351
- control change.
416
+ control change. A finding the report lists as "also in" other commits is
417
+ one secret seen in several commits (a merge reports a pull request's change
418
+ again), and each of those commits has its own fingerprint: put one line per
419
+ commit the finding lists, its own and each "also in", or the copy comes
420
+ back under another fingerprint. Two cautions. gitleaks drops an ignored
421
+ finding without reporting it, so conductor does not count it: unlike an
422
+ osv-scanner suppression, nothing in the report shows it. And one line
423
+ silences every secret on that line in that commit that the same rule
424
+ matches, not only the one you reviewed.
352
425
 
353
426
  4. **Switch to enforce.** When a few ordinary pull requests report only what
354
427
  you expect, remove `advisory: true`, and set `enforce: true` on the gates
@@ -542,8 +615,8 @@ request being judged, and the version-pin protection described above
542
615
  "protects nothing" against a tree that controls its own judge (the
543
616
  validate step's own comment in `action.yml` says so in those words). A tag
544
617
  moves when someone pushes it. Name this action by owner and the full commit
545
- SHA instead. The recipes in this README name v0.18.0 that way, as
546
- `vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0`.
618
+ SHA instead. The recipes in this README name v0.18.1 that way, as
619
+ `vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1`.
547
620
 
548
621
  ```yaml
549
622
  name: guardrails
@@ -565,7 +638,7 @@ jobs:
565
638
  with:
566
639
  node-version: '22.23.4'
567
640
  - id: conductor
568
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
641
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
569
642
  with:
570
643
  output: conductor.sarif
571
644
  - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
@@ -664,7 +737,7 @@ jobs:
664
737
  # installs those itself, globally. Leave conductor-version unset so the
665
738
  # umbrella is the default in the pinned action.yml.
666
739
  - id: conductor
667
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
740
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
668
741
  with:
669
742
  output: conductor.sarif
670
743
  # The gate versions are left out on purpose: the defaults travel
@@ -720,8 +793,9 @@ credential helpers, `core.sshCommand`), git hooks such as
720
793
  `reference-transaction`, and replace refs or grafts. (The action's fetch, gates
721
794
  and fallback render steps set `GIT_NO_REPLACE_OBJECTS=1` for themselves and
722
795
  for the gates they run, which narrows replace refs. The fetch step alone also
723
- reads through a graft file, for its decision to move the trust base; the gates
724
- and the CLI still see one.)
796
+ reads through a graft file, for its decision to move the trust base, and
797
+ since issue 101 so does every git call the CLI makes itself; a gate's own
798
+ git calls still read one.)
725
799
  Say it plainly: package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
726
800
  `prepare`) run by an install bypass "require review on `.github/workflows`",
727
801
  because the pull request supplies them, not the workflow file. Branch
@@ -733,7 +807,10 @@ shallow checkout on a pull-request run is could-not-run for the history gate,
733
807
  naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
734
808
  depth of 1 the checkout is shallow, the range from the base to HEAD holds one
735
809
  grafted commit, and a secret added and then removed inside the pull request
736
- would never be seen. conductor does not deepen the checkout for you.
810
+ would never be seen. conductor does not deepen the checkout for you. A run
811
+ with no base (a push, a scheduled run, a local run) has the same need: a
812
+ shallow checkout cuts the whole history it reads off at the graft, and the
813
+ history gate is could-not-run there too.
737
814
 
738
815
  **The two external gates are installed by your workflow, not by the
739
816
  Action.** The Action still installs exactly its four npm packages and has no
@@ -802,9 +879,10 @@ could-not-run (`timed-out`), never a pass.
802
879
  job before it can fire. Keep it well under.
803
880
 
804
881
  Measure your own full scan once, on the runner it will run on, and set the
805
- limit with headroom. The recommended split: every pull request scans its own
806
- range, and the full history is scanned on a schedule with a limit sized for
807
- it. Two existing ways to make it: by stage, since `secrets-history` defaults
882
+ limit with headroom. The recommended split, and the one the quick start
883
+ above uses: every pull request scans its own range, pushes to main run at
884
+ stage `push`, and the full history is scanned on a daily schedule with a limit
885
+ sized for it. Two existing ways to make it: by stage, since `secrets-history` defaults
808
886
  to stage `ci` and a push workflow run with the Action's `stage: push` input
809
887
  (or `conductor run --stage push`) leaves ci-stage gates out; or by trigger,
810
888
  running the workflow on pull requests and a schedule and not on push. With
@@ -887,7 +965,7 @@ jobs:
887
965
  # seconds) plus 300 seconds for the preview, rounded up. A step
888
966
  # timeout below that can kill a full gitleaks scan and leave no verdict.
889
967
  timeout-minutes: 30
890
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
968
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
891
969
  with:
892
970
  pr-comment: true
893
971
  advisory: true
@@ -977,23 +1055,40 @@ See "Adopting conductor: the careful path" near the top of this README for the o
977
1055
  walkthrough: init, a first pull request in advisory mode, merge, then go
978
1056
  required. This subsection is the mechanism behind two of those steps.
979
1057
 
980
- **Why the first pull request still exits 2 under `advisory: true`.**
981
- `advisory: true` maps a blocking **finding** to exit 0; it has no opinion
982
- about a run that never had a policy to be judged by. The pull request that
983
- first adds `.guardrails.yaml` is judged against the base branch, which has
984
- none yet, so the run is refused outright before any gate produces a finding
985
- for `advisory` to act on. Leaving the check out of branch protection for
986
- that one pull request is what keeps the expected exit 2 from blocking the
987
- merge; the step posts a comment naming the ref and the remedy.
988
-
989
- The same refusal happens once on every new base branch, not only on the
990
- default branch, because rules are read from whatever branch the pull request
991
- targets. A release or release-candidate branch cut before the policy existed,
992
- or any long-lived branch that has never received `.guardrails.yaml`, refuses
993
- its first pull request the same way. There are two remedies. Carry the policy
994
- onto the branch before opening a pull request against it; a sync from the
995
- default branch does this. Or expect exactly one could-not-run run there, and
996
- leave the check out of that branch's protection for that one pull request.
1058
+ **What the first pull request reports.** The pull request that first adds
1059
+ `.guardrails.yaml` is judged against the base branch, which has no policy
1060
+ yet, so nothing in it can be enforced. On a pull request into the
1061
+ repository's default branch the Action passes `--adoption-proposal`, and
1062
+ the run is a proposal: conductor runs the policy the pull request adds,
1063
+ taking only `enabled`, `stage` and `enforce` from the committed file, and
1064
+ exits 0 with the verdict `proposal (N)` and the line `proposal: no
1065
+ .guardrails.yaml on the base branch, so nothing here was enforced; N would
1066
+ block once this policy is on the base branch`. It exits 2 when a gate that
1067
+ policy enforces could not run. `advisory` has no part in either outcome.
1068
+ The full rules are under [A proposal](docs/commands.md#a-proposal).
1069
+
1070
+ A proposal is only for a first adoption. The run is refused, exit 2, when
1071
+ the base branch has carried a policy before (one was deleted, and a later
1072
+ pull request adds one back), when the pull request inherited its policy
1073
+ from a base that has since dropped it, in a shallow checkout, or when the
1074
+ workflow has no policy on either side (the summary then says `no-policy:
1075
+ this workflow checks nothing until .guardrails.yaml is on the base branch`).
1076
+ After a deletion, the policy has to be landed on the base branch by someone
1077
+ allowed to merge without this check passing.
1078
+
1079
+ A pull request into any other branch gets no proposal, because rules are
1080
+ read from whatever branch the pull request targets and a missing policy
1081
+ there may be a gap. A release or release-candidate branch cut before the
1082
+ policy existed, or any long-lived branch that has never received
1083
+ `.guardrails.yaml`, refuses its first pull request with exit 2, under
1084
+ `advisory: true` as well: `advisory` maps a blocking **finding** to exit 0
1085
+ and has no opinion about a run with no policy to be judged by. There are
1086
+ two remedies. Carry the policy onto the branch before opening a pull
1087
+ request against it; a sync from the default branch does this. Or expect
1088
+ exactly one could-not-run run there, and leave the check out of that
1089
+ branch's protection for that one pull request.
1090
+
1091
+ A merge queue run (`merge_group`) never gets a proposal either.
997
1092
 
998
1093
  **Why "go required" means the job's own context, never the SARIF-upload
999
1094
  row.** The recipes above upload conductor's SARIF log with
@@ -1023,7 +1118,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1023
1118
  # the pull request runs before the action in this job: no install, build
1024
1119
  # or test step here; those belong in a separate job. ...
1025
1120
  - id: conductor
1026
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1121
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
1027
1122
  with:
1028
1123
  output: conductor.sarif
1029
1124
  pr-comment: true
@@ -1043,14 +1138,48 @@ a re-run find and update that same comment, so a push does not pile up a new
1043
1138
  comment every time, the way the manual recipe below does. It runs on a
1044
1139
  `pull_request` or `pull_request_target` event only, and it runs whether the
1045
1140
  gates step passed or failed, since a blocking run is the one an advisory
1046
- check most needs a developer to actually see. The first line of every
1047
- comment carries the version of conductor that produced it, the second line
1048
- carries the verdict token (see [The verdict token](docs/commands.md#the-verdict-token)), and when the
1049
- trust base was refused and no gate ran at all, the comment shrinks to the
1050
- version, the verdict, and the refusal reason (with its remedy, when one
1051
- applies) rather than the full per-gate report, so an adopter with no policy
1052
- on the base ref yet does not get a full sticky comment whose only content is
1053
- "refused, nothing checked" on every push.
1141
+ check most needs a developer to actually see.
1142
+
1143
+ **What the comment looks like.** It leads with the verdict, then one row per
1144
+ gate, then the findings by name, and the whole report is collapsed under
1145
+ them, one click away:
1146
+
1147
+ ```text
1148
+ conductor verdict: blocked (1)
1149
+
1150
+ gate dependencies (dep-guard 0.20.0): ran, exit 0, 0 blocking
1151
+ gate secrets (vault-guard 1.13.3): ran, exit 1, 1 blocking
1152
+ gate vulnerabilities (osv-scanner version unknown): did not run (binary-missing)
1153
+
1154
+ findings: 14 (12 blocking), the first 10:
1155
+ finding: BLOCKING vault-guard vault-guard/github-token src/config.js:2: Possible secret of type 'github-token'
1156
+ ...
1157
+ and 2 more blocking
1158
+ ```
1159
+
1160
+ A gate line says `ran`, with the gate's own version, its exit code and how
1161
+ many findings it marked blocking, or `did not run`, with the reason, or
1162
+ `skipped` or `disabled`, with why. A gate that did not run never reads as
1163
+ one that passed. A line such as `ran, exit 1, 0 blocking` under a `pass` is
1164
+ the gate's own exit code for findings that do not block this run: the
1165
+ vulnerabilities gate exits 1 on advisories that were already on the base
1166
+ branch, which conductor reports and does not block on. The findings line
1167
+ counts every finding and names only the ones that block, the first ten of
1168
+ them; when none blocks it is the count alone, `findings: 77 (0 blocking)`,
1169
+ and the rest are in the report. When the installed gate is not the version the action
1170
+ pinned, the line prints both (`did not run (version-skew), the action pinned
1171
+ 0.20.0`). When the vulnerabilities gate compared the pull request with the
1172
+ base branch, the comment leads with `new in this pull request: N
1173
+ (vulnerabilities gate; M already on the base)`; no other gate compares with
1174
+ the base, so the line is absent on a run where that comparison did not
1175
+ happen. Inside the collapsed report the first line carries the version of
1176
+ conductor that produced it and the second the verdict token (see
1177
+ [The verdict token](docs/commands.md#the-verdict-token)). When the trust
1178
+ base was refused and no gate ran at all, the report under the gate rows
1179
+ shrinks to the version, the verdict, and the refusal reason (with its
1180
+ remedy, when one applies) and starts open, so a refused run
1181
+ does not get a full sticky comment whose only content is "refused, nothing
1182
+ checked" on every push.
1054
1183
 
1055
1184
  **It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
1056
1185
  there is read-only regardless of the `pull-requests: write` permission you
@@ -1076,6 +1205,20 @@ could not be verified and no gate ran, the summary says
1076
1205
  `could-not-run`. The output is empty when the installed `conductor-version`
1077
1206
  predates the token.
1078
1207
 
1208
+ **The job summary names the gates and the findings too.** Under the verdict
1209
+ line the summary carries the same rows the comment leads with: one line per
1210
+ gate (`ran`, `did not run`, `skipped` or `disabled`, as above), then the
1211
+ count of findings and the first ten that block, by gate, rule, place and
1212
+ reason, then `and N more blocking`. The job log prints the same finding
1213
+ lines. So a run that blocked says what it
1214
+ caught without anybody opening the SARIF log, and a run where a gate could
1215
+ not run says which gate and why on the page a reviewer already looks at.
1216
+ Those lines are copied from the head of the text report, by position: a gate
1217
+ line only when the whole line is built from conductor's own words and
1218
+ numbers, and a finding line (whose path, package name and message come from
1219
+ the scanned repository) only inside a code block, after conductor has
1220
+ escaped and shortened each field.
1221
+
1079
1222
  **The sticky match only ever adopts conductor's own comment.** On
1080
1223
  `pull_request_target` this step runs with a write token even though the
1081
1224
  pull request itself is untrusted, so anyone who can comment on the pull
@@ -1102,12 +1245,12 @@ per pull request.
1102
1245
 
1103
1246
  ```yaml
1104
1247
  - id: conductor-package-a
1105
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1248
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
1106
1249
  with:
1107
1250
  pr-comment: true
1108
1251
  pr-comment-marker: 'package-a'
1109
1252
  - id: conductor-package-b
1110
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1253
+ uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
1111
1254
  with:
1112
1255
  pr-comment: true
1113
1256
  pr-comment-marker: 'package-b'
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Every GIT_ variable in `env` that is not on the allowlist, sorted. Matched
3
+ * on the upper-cased name, so a lower-case spelling (which Windows treats as
4
+ * the same variable) is caught, and present-but-empty counts: git treats
5
+ * several of these as set whatever they hold.
6
+ */
7
+ export declare function disallowedGitVariables(env: NodeJS.ProcessEnv): string[];
8
+ /**
9
+ * The entries at the root of `commit`'s tree whose name is the policy file
10
+ * name under another spelling (`.Guardrails.yaml`), or the reason the root
11
+ * could not be listed.
12
+ *
13
+ * `src/policy.ts#loadPolicy` reads the policy from disk by name, so on a
14
+ * case-insensitive file system (the macOS runners) a push run finds and
15
+ * enforces `.Guardrails.yaml`, while every read from a ref here asks git for
16
+ * the exact name and is told there is none. Such a base has a policy.
17
+ */
18
+ export declare function policyNameVariants(repoRoot: string, commit: string): {
19
+ kind: 'listed';
20
+ names: string[];
21
+ } | {
22
+ kind: 'error';
23
+ detail: string;
24
+ };
25
+ /**
26
+ * Why this run is NOT an adoption proposal, or null when every condition
27
+ * holds. Called only after the caller has established that the flag was
28
+ * given, that the trust base passed its own checks, that the exact policy
29
+ * file name is absent in the trust base's tree, and that the HEAD blob
30
+ * parses.
31
+ *
32
+ * The reason is one or two sentences for the refusal the caller reports;
33
+ * every enabled gate is then could-not-run and the run exits 2, exactly as
34
+ * on a base without a policy before this file existed.
35
+ */
36
+ export declare function refuseAdoptionProposal(repoRoot: string, trustBase: string, env?: NodeJS.ProcessEnv): string | null;