@vaultcompass/conductor 0.7.0 → 0.8.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/README.md CHANGED
@@ -167,7 +167,7 @@ required.
167
167
  A commit with a staged credential in it prints the full report and exits 1:
168
168
 
169
169
  ```
170
- conductor 0.7.0
170
+ conductor 0.8.0
171
171
  verdict-token: blocked (1)
172
172
  conductor run: 2 gate(s), 1 finding(s)
173
173
 
@@ -473,7 +473,8 @@ proceeds normally without mentioning them.
473
473
  pull-request run passes both: `--base` decides which paths are judged,
474
474
  `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
475
475
  set, an explicit `--trust-base` is accepted only when it resolves to the
476
- same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
476
+ same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
477
+ private `refs/conductor/trust-base` (issue #58); anyone invoking the
477
478
  CLI directly on a pull request, rather than through the Action, gets this
478
479
  as its own refusal, named below.
479
480
  - `--spec <path>` names the spec the intent gate imports its contract from.
@@ -571,6 +572,11 @@ code and the `enforce` flags the run already had.
571
572
 
572
573
  - `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
573
574
  could not run.
575
+ - `nothing-checked`: exit 0, but no gate ran at all (none is enabled, or
576
+ every enabled one was deferred to a later stage, had nothing to judge, or
577
+ was skipped). The exit status is unchanged, since nothing failed, but this
578
+ is not a pass: nothing was verified. In the Action the `verdict` output
579
+ carries this token, so a workflow can tell it apart from `pass`.
574
580
  - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
575
581
  it exit 0. N is the blocking findings on enforced gates.
576
582
  - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
@@ -580,11 +586,13 @@ code and the `enforce` flags the run already had.
580
586
  - `could-not-run`: exit 2, a refused trust base included.
581
587
 
582
588
  When several apply the order is `could-not-run`, then `blocked` or
583
- `advisory-blocked`, then `unenforced-findings`, then `pass`. A run with
589
+ `advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
590
+ ran) or `pass`. A run with
584
591
  `--advisory` whose only blocking findings sit on an unenforced gate is
585
592
  `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
586
593
  there. A gate skipped for want of a contract does not by itself move the token
587
- off `pass`; the verdict sentence is where "nothing was checked" is said. A
594
+ off `pass` when another gate ran; when no gate ran, the token is
595
+ `nothing-checked` and the verdict sentence says "nothing was checked". A
588
596
  gate that exited non-zero with no finding marked blocking counts as one in N,
589
597
  so a state that is not a pass never prints a count of zero. The one-line
590
598
  summary of a clean, non-verbose run has no token line, since it is one line by
@@ -602,7 +610,12 @@ request could point a gate at a script it added in the same commit.
602
610
 
603
611
  **On a pull-request run the rules come from the base branch.** With
604
612
  `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
605
- `git show` and judges the head tree against it. A `.guardrails.yaml` in the
613
+ git and judges the head tree against it. A trusted file at the base that git
614
+ cannot read as a regular file (a symlink, a directory, a submodule, or a file
615
+ below a symlinked or submodule directory) is could-not-run, never replaced by
616
+ a default. Clear it by making the file a regular file on the base branch; the
617
+ pull request that does so is judged against that same base, so it has to be
618
+ merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
606
619
  pull request never takes effect for that run, `command:` and `args:`
607
620
  included, so **a pull request cannot change the rules it is judged by, and
608
621
  cannot choose the program that judges it, as long as that program is
@@ -737,15 +750,19 @@ to remove the input; see "The Action" below.
737
750
 
738
751
  **The CLI check catches a misconfigured or innocent-looking redirect when
739
752
  `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
740
- that variable is set, an explicit `--trust-base` is accepted only when it
741
- resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
742
- what the Action itself always passes, so an ordinary pull-request run is
753
+ that variable is set, an explicit `--trust-base` is accepted only when it is
754
+ `refs/conductor/trust-base`, the private ref the Action fetches the base
755
+ branch into and always passes (that ref is the authority and is not compared
756
+ with anything), or resolves to the same commit as
757
+ `refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
743
758
  unaffected. A ref naming the pull request's own branch, or anything else that
744
759
  disagrees, is refused with both refs and both commits named, through the same
745
760
  could-not-run path as every other trust-base refusal: exit 2, the report
746
- leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
747
- itself does not resolve, this fails closed too, naming it, for the same
748
- reason the fetch-depth remedy below exists.
761
+ leads with the reason, and nothing is checked. A short name that matches both
762
+ a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
763
+ refused as ambiguous: spell the ref in full. When neither resolves, this fails
764
+ closed too, naming it, for the same reason the fetch-depth remedy below
765
+ exists.
749
766
 
750
767
  **Neither layer closes anything against a pull request that edits its own
751
768
  workflow file.** A CLI invocation on a pull request can simply omit
@@ -811,10 +828,11 @@ choose its own judge on exactly the repositories that have no rules yet. See
811
828
  "Adopting conductor" below for the sequence and for how to see what your
812
829
  policy will do before you merge it.
813
830
 
814
- **Which gates are covered.** All five: dep-guard from **0.6.0**,
815
- intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
831
+ **Which gates are covered.** All five: dep-guard from **0.10.1**,
832
+ intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
816
833
  external gates at their command-line floors, gitleaks **8.19.0** and
817
- osv-scanner **2.0.0**.
834
+ osv-scanner **2.0.0**. On a pull-request run an older family gate is
835
+ could-not-run rather than run outside pull-request mode.
818
836
 
819
837
  **The external gates get their pull-request mode from the umbrella.**
820
838
  Neither tool has a `--trust-base`, and both auto-load a config from the tree
@@ -872,22 +890,50 @@ in the diff. Only the root `osv-scanner.toml` is read from the base and
872
890
  passed with `--config`, which overrides any nested one for the run; a
873
891
  nested one the pull request adds or edits is reported as a proposal.
874
892
 
875
- The umbrella asks each gate its version and passes the flag only to a build
876
- that understands it, so an older gate is not handed a flag it would reject. A
877
- gate that was not put into pull-request mode read its own rules out of the
878
- tree being judged, which is the thing this exists to prevent, so it is never
879
- silent: it gets a line in the report, a clause on the clean one-line summary,
880
- and a `conductor/trust-base-not-passed` notification in the SARIF log. For a
881
- gate that IS in the table, a version that cannot be read at all is
882
- could-not-run rather than a quiet downgrade: the umbrella cannot establish
883
- that the gate would take its rules from the base ref, and running it anyway
884
- would put it outside the boundary on exactly the runs where something is
885
- already wrong.
893
+ The umbrella asks each gate its version before it runs it. On a run with a
894
+ trust base, a gate older than its pull-request-mode minimum (intent-guard
895
+ 1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
896
+ never run without the flag: without it the gate would take its rules from
897
+ the tree being judged. The fix is to install that minimum or newer, or to
898
+ remove an explicit older version pin. A version that cannot be read at all
899
+ is could-not-run too: the umbrella cannot establish that the gate would
900
+ take its rules from the base ref. The one gate that runs without the flag
901
+ is an intent gate judging a contract imported from the base for the run,
902
+ whose project is a temporary directory with no repository to resolve a ref
903
+ in; that is never silent: it gets a line in the report, a clause on the
904
+ clean one-line summary, and a `conductor/trust-base-not-passed`
905
+ notification in the SARIF log.
886
906
 
887
907
  Outside pull-request mode nothing changes. A pre-commit hook and a direct run
888
908
  on your own checkout are already inside the trust boundary, and neither passes
889
909
  the flag.
890
910
 
911
+ **In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
912
+ `GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
913
+ rules have to come from the base branch, and no base was named. Pass `--trust-base
914
+ refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
915
+ which always passes one. A pre-commit hook run inside a pull-request job hits
916
+ this too: skip the hook in CI, or pass the trust base to it.
917
+
918
+ **On a pull-request run PATH holds only absolute entries, and conductor's own
919
+ git comes from outside the repository.** Empty and relative entries are
920
+ removed for conductor and every gate it starts, with one notice naming them,
921
+ and conductor runs the first git on PATH that lives outside the repository's
922
+ work tree; with none, the run is could-not-run and says to put git's own
923
+ directory on PATH. A gate found only through a removed entry is reported
924
+ missing; put it on an absolute PATH entry or name it with an absolute
925
+ `command:`. Every gate conductor starts, and everything a gate starts, gets
926
+ a PATH whose first entry is a private directory outside the repository
927
+ holding only that same git, so a gate that runs git by name runs it too; on
928
+ Windows no such directory is made and the gates look git up through the
929
+ cleaned PATH, and a system temp directory inside the repository is
930
+ could-not-run until TMPDIR names one outside it.
931
+
932
+ **git 2.31 or later** is needed on a pull-request run with the secrets-history
933
+ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
934
+ which arrived in git 2.31. Only that gate checks: an older git makes it
935
+ could-not-run, naming the version, and the other gates run.
936
+
891
937
  ## Intent at a pull request
892
938
 
893
939
  The intent gate is the only one of the five with any ceremony: its native
@@ -899,8 +945,13 @@ human step. That step is exactly what a pull request cannot carry, so at the
899
945
  branch changed since it forked, from
900
946
  `git diff --name-only --no-renames <base>...HEAD` in the repository root.
901
947
 
902
- With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
903
- set, and the text report says so. With neither, the intent gate runs the way
948
+ With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
949
+ `refs/conductor/trust-base` (the Action's private fetch of the base) if that
950
+ exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
951
+ shadow it. The text report says which. An explicit `--base` that matches both
952
+ a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
953
+ (merge_group, workflow_dispatch, a CLI run), the change set is measured from
954
+ the trust base. With none of the three, the intent gate runs the way
904
955
  it does at a commit: against the staged index, or the paths you name.
905
956
 
906
957
  **This is why a local preview and a pull-request run can disagree about a
@@ -923,12 +974,31 @@ fallback to an empty path set, because an empty path set is what a passing
923
974
  gate looks like. In Actions this is almost always a shallow checkout, so
924
975
  **`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
925
976
 
977
+ **On a pull-request run the base decides.** With `--trust-base`, whether a
978
+ frozen contract governs the pull request is read from the base ref alone. A
979
+ frozen contract on the base is used, ahead of everything in the list below,
980
+ `--spec` included (the report says so when `--spec` was given), and the gate
981
+ judges any edit to it against the base copy. That holds for every
982
+ intent-guard that can run on a pull-request run, since one older than its
983
+ pull-request-mode minimum is could-not-run rather than run without the base
984
+ ref. With no frozen contract on the
985
+ base, nothing in the pull request becomes the contract: a spec on the base,
986
+ found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
987
+ run `--spec` must be a plain path inside the repository that the base
988
+ carries), and otherwise
989
+ the gate is skipped with "No contract on the base". A contract or spec the
990
+ pull request adds is reported as a proposal, so adopting the intent gate
991
+ merges, and the next pull request is judged against it. Retiring or replacing
992
+ a frozen contract through a judged pull request is refused by the intent gate
993
+ itself and needs an administrator to merge it.
994
+
926
995
  **Where the contract comes from**, in order:
927
996
 
928
997
  1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
929
- outranks everything, and a path here that is not on disk is reported
930
- rather than replaced: running a different contract than the one somebody
931
- named is the wrong kindness.
998
+ outranks everything else in this list, and a path here that is not on
999
+ disk is reported rather than replaced: running a different contract than
1000
+ the one somebody named is the wrong kindness. On a pull-request run it is
1001
+ read from the base, and a frozen contract on the base takes precedence.
932
1002
  2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
933
1003
  `<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
934
1004
  wherever a team has done it. Frozen is the test rather than present: an
@@ -1092,14 +1162,18 @@ provenance even though all four packages publish it.
1092
1162
  > sigstore outage has the same effect. The audit is retried once after a short
1093
1163
  > pause before the step fails, to absorb a one-off registry hiccup. It fails
1094
1164
  > closed on purpose, so that is a red gate rather than a skipped check; pin to
1095
- > `@v0.4.0`, which does not verify, if it blocks you.
1165
+ > `45d2ecc2213244408495c22d0b8da1dc0f1ed288` (v0.4.0), which does not verify,
1166
+ > if it blocks you.
1096
1167
 
1097
1168
  `--base` is passed only when the `base-ref` input names one; left empty, the
1098
1169
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
1099
1170
  pull request", which is what a push build wants.
1100
1171
 
1101
- On a `pull_request` event the action passes
1102
- **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
1172
+ On a `pull_request` event a dedicated step fetches the base branch into a
1173
+ private ref and the action passes **`--trust-base <the fetched commit id>`**
1174
+ of its own accord (the job needs `contents: read`; a failed fetch fails the job
1175
+ rather than running without a trust base; the token exists only in that fetch
1176
+ step and never in the gates), so the run takes
1103
1177
  its configuration from the base branch and the pull request cannot change the
1104
1178
  rules it is judged by; a change to the rules shows as a proposal line and
1105
1179
  takes effect after merge. See "The pull-request trust boundary" above. On any
@@ -1113,7 +1187,8 @@ workflow file is the *base* branch's own instead, but the input is refused
1113
1187
  there too, because pull-request mode already derives the trust base on both
1114
1188
  events and an explicit redirect has no legitimate use on either. The refusal
1115
1189
  names the value that was given and the fix, which is to remove the input: the
1116
- action already derives `origin/$GITHUB_BASE_REF` itself on that event.
1190
+ action already derives the private `refs/conductor/trust-base` itself on that
1191
+ event.
1117
1192
 
1118
1193
  There is deliberately **no input that turns pull-request mode off**.
1119
1194
  Base-ref judging is the floor rather than a knob, and on a `pull_request`
@@ -1121,14 +1196,16 @@ event the workflow file itself runs from the pull request's own ref, so an
1121
1196
  opt-out here would be settable by the very pull request the mode exists to
1122
1197
  judge: the knob and the thing it protects against would be the same file.
1123
1198
 
1124
- **The normal way to use this is by tag, not by path.** `uses: ./` reads
1199
+ **Pin the action by full commit SHA, with the version in a trailing comment, not by tag and not by path.** `uses: ./` reads
1125
1200
  `action.yml` out of whichever tree the workflow runs against, which is
1126
1201
  correct only for this repository's own workflows testing themselves; on a
1127
1202
  pull request from anywhere else it would read `action.yml` out of the pull
1128
1203
  request being judged, and the version-pin protection described above
1129
1204
  "protects nothing" against a tree that controls its own judge (the
1130
- validate step's own comment in `action.yml` says so in those words). Name
1131
- this action by owner and tag instead:
1205
+ validate step's own comment in `action.yml` says so in those words). A tag
1206
+ moves when someone pushes it. Name this action by owner and the full commit
1207
+ SHA instead. The recipes in this README pin the v0.8.0 commit and are
1208
+ updated to the v0.8.1 commit after that release is tagged.
1132
1209
 
1133
1210
  ```yaml
1134
1211
  name: guardrails
@@ -1143,12 +1220,14 @@ jobs:
1143
1220
  steps:
1144
1221
  - uses: actions/checkout@v7
1145
1222
  with:
1223
+ # From 0.8.0 a shallow checkout on a pull-request run is
1224
+ # could-not-run for the history gate.
1146
1225
  fetch-depth: 0
1147
1226
  - uses: actions/setup-node@v7
1148
1227
  with:
1149
1228
  node-version: '22.11.0'
1150
1229
  - id: conductor
1151
- uses: vaultcompasshq/conductor@v0.7.0
1230
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1152
1231
  with:
1153
1232
  output: conductor.sarif
1154
1233
  - uses: github/codeql-action/upload-sarif@v3
@@ -1158,6 +1237,10 @@ jobs:
1158
1237
  sarif_file: ${{ steps.conductor.outputs.sarif }}
1159
1238
  ```
1160
1239
 
1240
+ The job has `permissions: contents: read`. Add `pull-requests: write` only
1241
+ where the recipe posts a comment. `security-events: write` is there because
1242
+ the upload step publishes the SARIF log.
1243
+
1161
1244
  The examples leave the trigger unnarrowed on purpose, so the job runs for a
1162
1245
  pull request into any branch. If you narrow it with a `branches:` filter,
1163
1246
  include every branch whose merges reach users, release branches and the
@@ -1166,11 +1249,20 @@ production]`. The pull request that promotes a release is where a bad
1166
1249
  dependency or a leaked secret actually ships, and a job that is not triggered
1167
1250
  leaves no red check and no report to notice.
1168
1251
 
1169
- No version inputs there at all: left out, the four gates run at the versions
1170
- this tag ships, which is the intended default. The fully spelled-out example
1171
- below adds explicit version pins and comments explaining each one, for a
1172
- workflow that wants that transparency; the four lines can still be left out
1173
- entirely to take the tag's own versions, exactly as the form above does.
1252
+ A job marked `continue-on-error` always concludes green, so a crash of the
1253
+ action is invisible unless someone opens the log. A workflow triggered only
1254
+ on pull requests to main never runs on a stacked pull request whose base is
1255
+ another branch, and no comment on such a pull request does not mean clean.
1256
+
1257
+ Omit `conductor-version`. Left unset, the action installs the default in the
1258
+ pinned `action.yml`, which is the version that commit ships, so the installed
1259
+ umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
1260
+ input is set and is older than the constants in that pinned action.yml, a
1261
+ pull request run is refused and the validate step says to remove the input. A
1262
+ newer value is accepted and is what gets installed. The three gate version
1263
+ inputs can be left out too: each one then takes the default in the pinned
1264
+ action.yml. The spelled-out example below names them when a workflow wants
1265
+ that transparency.
1174
1266
 
1175
1267
  ```yaml
1176
1268
  name: guardrails
@@ -1185,13 +1277,14 @@ jobs:
1185
1277
  steps:
1186
1278
  - uses: actions/checkout@v7
1187
1279
  with:
1188
- # Required, for two reasons now. Without it there is no merge base
1189
- # to diff against, and the intent gate fails closed rather than
1190
- # checking an empty set. And the base ref itself has to be in the
1191
- # clone, because on a pull request the rules are read from it: a
1192
- # base ref that will not resolve is exit 2 for every enabled gate.
1280
+ # Required. From 0.8.0 a shallow checkout on a pull-request run is
1281
+ # could-not-run for the history gate. Without a full history there
1282
+ # is no merge base to diff against, and the intent gate fails closed
1283
+ # rather than checking an empty set. And the base ref itself has to
1284
+ # be in the clone, because on a pull request the rules are read from
1285
+ # it: a base ref that will not resolve is exit 2 for every enabled
1286
+ # gate.
1193
1287
  fetch-depth: 0
1194
- - uses: pnpm/action-setup@v4
1195
1288
  - uses: actions/setup-node@v7
1196
1289
  with:
1197
1290
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
@@ -1199,27 +1292,30 @@ jobs:
1199
1292
  # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
1200
1293
  # can verify.
1201
1294
  node-version: '22.11.0'
1202
- cache: pnpm
1203
- # Your own dependencies. The gates are NOT among the things this has to
1204
- # install: the action installs those itself, globally, at the versions
1205
- # pinned below.
1206
- - run: pnpm install --frozen-lockfile
1295
+ # NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
1296
+ # No `pnpm install`, `npm ci`, build or test step: an install runs the
1297
+ # repository's own lifecycle scripts (a root postinstall), and that code
1298
+ # could write the PATH the gates are resolved from, or the refs the
1299
+ # policy is read from, before the gates ever start. Your own
1300
+ # dependencies, build and tests belong in a separate job (see below).
1301
+ # The gates are not among the things that job has to install: the action
1302
+ # installs those itself, globally. Leave conductor-version unset so the
1303
+ # umbrella is the default in the pinned action.yml.
1207
1304
  - id: conductor
1208
- uses: vaultcompasshq/conductor@v0.7.0
1305
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1209
1306
  with:
1210
1307
  output: conductor.sarif
1211
- # Exact versions, never a range and never "latest". These four
1212
- # lines decide which programs judge a pull request, so a pull
1308
+ # Exact versions, never a range and never "latest". These three
1309
+ # lines decide which gate programs judge a pull request, so a pull
1213
1310
  # request's own lockfile no longer does. They are only as protected
1214
1311
  # as this file is: require review on .github/workflows in your
1215
1312
  # branch protection. Bump them like any other pin, in a pull
1216
- # request of their own. Forward only on a pull request: the action
1217
- # refuses a pin below what its tag ships, and the four lines can be
1218
- # left out entirely to take that tag's own versions.
1219
- conductor-version: 0.7.0
1220
- dep-guard-version: 0.9.0
1221
- vault-guard-version: 1.8.0
1222
- intent-guard-version: 1.7.0
1313
+ # request of their own. On a pull request the action refuses a pin
1314
+ # below what the pinned action.yml ships, and the three lines can
1315
+ # be left out entirely to take that action's own versions.
1316
+ dep-guard-version: 0.10.0
1317
+ vault-guard-version: 1.9.0
1318
+ intent-guard-version: 1.8.0
1223
1319
  - uses: github/codeql-action/upload-sarif@v3
1224
1320
  # Always: the log is most worth having on the run that failed.
1225
1321
  if: always()
@@ -1233,8 +1329,49 @@ jobs:
1233
1329
  continue-on-error: true
1234
1330
  with:
1235
1331
  sarif_file: ${{ steps.conductor.outputs.sarif }}
1332
+
1333
+ # Your own dependencies, build and tests: a different job, so the code they
1334
+ # run shares no runner, PATH or workspace with the gates.
1335
+ build:
1336
+ runs-on: ubuntu-latest
1337
+ steps:
1338
+ - uses: actions/checkout@v7
1339
+ - uses: pnpm/action-setup@v4
1340
+ - uses: actions/setup-node@v7
1341
+ with:
1342
+ node-version: '22.11.0'
1343
+ cache: pnpm
1344
+ - run: pnpm install --frozen-lockfile
1345
+ - run: pnpm test
1236
1346
  ```
1237
1347
 
1348
+ **Run the gates in a job that runs no code from the pull request.** Do not
1349
+ run `pnpm install`, `npm ci`, a build or a test step before the conductor
1350
+ action in the same job, and do not put the action in a job whose earlier steps
1351
+ run the repository's own scripts. Anything that runs first shares the runner
1352
+ with the gates: it can write to `GITHUB_PATH`, to the runner's temp directory
1353
+ where the action installs the gates, or to the git refs the base policy is
1354
+ read from, and then it is the pull request choosing the program that judges
1355
+ it. The action fetches the base branch into its own private ref and judges by
1356
+ that, which closes a moved or tag-shadowed base ref and nothing else. Only
1357
+ keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
1358
+ (`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
1359
+ `.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
1360
+ credential helpers, `core.sshCommand`), git hooks such as
1361
+ `reference-transaction`, and replace refs or grafts. Say it plainly:
1362
+ package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
1363
+ `prepare`) run by an install bypass "require review on `.github/workflows`",
1364
+ because the pull request supplies them, not the workflow file. Branch
1365
+ protection on the workflow directory does not stop them, so the gates must
1366
+ not share a job with head code that runs first.
1367
+
1368
+ **With gitleaks enabled the checkout must be `fetch-depth: 0`.** From 0.8.0 a
1369
+ shallow checkout on a pull-request run is could-not-run for the history gate,
1370
+ naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
1371
+ depth of 1 the checkout is shallow, the range from the base to HEAD holds one
1372
+ grafted commit, and a secret added and then removed inside the pull request
1373
+ would never be seen. conductor does not deepen the checkout for you.
1374
+
1238
1375
  **The two external gates are installed by your workflow, not by the
1239
1376
  Action.** The Action still installs exactly its four npm packages and has no
1240
1377
  input for gitleaks or osv-scanner; conductor downloads, pins and checksums
@@ -1259,12 +1396,15 @@ checksum, the same way you would for a standalone security job:
1259
1396
  echo "$bin" >> "$GITHUB_PATH"
1260
1397
  ```
1261
1398
 
1262
- `fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
1263
- pull request conductor scans `<base>..HEAD`, and a base that was never
1264
- fetched is a git error gitleaks itself would report as a clean scan of
1265
- nothing. conductor reads that error off gitleaks' log and reports the gate
1266
- as could-not-run instead. A missing tool is could-not-run as well, with the
1267
- install step named in the report.
1399
+ `fetch-depth: 0` on the checkout is required with gitleaks enabled: on a
1400
+ pull request conductor scans `<base>..HEAD`. At depth 1 the checkout is
1401
+ shallow and that range holds a single commit, so a secret added and removed
1402
+ inside the pull request would go unseen; conductor detects the shallow
1403
+ checkout and reports the gate as could-not-run instead of scanning it. (A
1404
+ base that was never fetched at all is a git error gitleaks itself would
1405
+ report as a clean scan of nothing; conductor reads that error off gitleaks'
1406
+ log and reports the gate as could-not-run too.) A missing tool is
1407
+ could-not-run as well, with the install step named in the report.
1268
1408
 
1269
1409
  The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
1270
1410
  runs whatever its author pushes to it next. Pin every third-party action by
@@ -1305,21 +1445,24 @@ jobs:
1305
1445
  steps:
1306
1446
  - uses: actions/checkout@v7
1307
1447
  with:
1448
+ # From 0.8.0 a shallow checkout on a pull-request run is
1449
+ # could-not-run for the history gate.
1308
1450
  fetch-depth: 0
1309
1451
  - uses: actions/setup-node@v7
1310
1452
  with:
1311
1453
  node-version: '22.11.0'
1312
1454
  - id: conductor
1313
1455
  timeout-minutes: 5
1314
- uses: vaultcompasshq/conductor@v0.7.0
1456
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1315
1457
  with:
1316
1458
  pr-comment: true
1317
1459
  advisory: true
1318
1460
  ```
1319
1461
 
1320
- `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
1321
- the checkout does not already carry it (see the changelog entry for that
1322
- version), so this recipe needs no separate "fetch the base ref" step. None of
1462
+ `action.yml` fetches the trust base itself on every pull-request run, into its
1463
+ own private ref (depth 1 only when the checkout is already shallow, and always,
1464
+ whether or not the checkout carries the base), so this recipe needs no separate
1465
+ "fetch the base ref" step. None of
1323
1466
  the three steps above swallows its own exit code: a checkout or setup-node
1324
1467
  failure is an infrastructure problem this recipe should still surface, and
1325
1468
  the `conductor` step's own advisory behaviour comes from `advisory: true`
@@ -1442,9 +1585,11 @@ step and add `pull-requests: write` to the job's `permissions`:
1442
1585
  security-events: write
1443
1586
  pull-requests: write
1444
1587
  steps:
1445
- # ... checkout, pnpm, setup-node, install, as in the example above ...
1588
+ # ... checkout and setup-node, as in the example above. Nothing from
1589
+ # the pull request runs before the action in this job: no install, build
1590
+ # or test step here; those belong in a separate job. ...
1446
1591
  - id: conductor
1447
- uses: vaultcompasshq/conductor@v0.7.0
1592
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1448
1593
  with:
1449
1594
  output: conductor.sarif
1450
1595
  pr-comment: true
@@ -1516,12 +1661,12 @@ per pull request.
1516
1661
 
1517
1662
  ```yaml
1518
1663
  - id: conductor-package-a
1519
- uses: vaultcompasshq/conductor@v0.7.0
1664
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1520
1665
  with:
1521
1666
  pr-comment: true
1522
1667
  pr-comment-marker: 'package-a'
1523
1668
  - id: conductor-package-b
1524
- uses: vaultcompasshq/conductor@v0.7.0
1669
+ uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
1525
1670
  with:
1526
1671
  pr-comment: true
1527
1672
  pr-comment-marker: 'package-b'