ci: cover every workflow with the hardening guards, and fix the gaps they surface

[dberzan]

Summary

Closes #125.

tests/test_ci_workflows.py already encodes two CI hardening invariants — every action pinned to a commit SHA, and no checkout persisting credentials — but both iterated the hardcoded tuple ("ci.yml", "security.yml"). dco.yml and publish-docs.yml were never loaded, and both had drifted.

workflow	every action SHA-pinned	permissions: declared	persist-credentials: false
ci.yml	yes	yes	10 / 10
security.yml	yes	yes	4 / 4
dco.yml	yes	yes	0 / 1 → 1 / 1
publish-docs.yml	no	no	0 / 1 → 1 / 1

The workflows

publish-docs.yml is the only workflow that puts a secret in a job environment (FERN_TOKEN), and was the least hardened of the four.

• actions/checkout@v4 was the single unpinned uses: reference out of 36 in the repository. It now uses 9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0, the SHA already used 14 times here.
• It had no permissions: block, so the job inherited the repository default GITHUB_TOKEN scope. It now declares contents: read, matching the other three workflows.
• It had no persist-credentials: false, so the token was written to .git/config and stayed readable by every later step in the job — including npm install and fern generate.
• npm install -g fern-api resolved its whole transitive tree at run time. It now installs the version fern/fern.config.json pins, derived exactly as ci.yml's docs lane already does, with the same format guard and a pinned setup-node so the lookup does not depend on the runner's ambient Node. Docs are now validated and published by the same CLI version — a hardcoded pin here would have let those two drift, which is the mistake my first attempt made.

dco.yml only reads history with git log and git show, so it gets persist-credentials: false too.

The guards

Both existing guards now glob .github/workflows/ rather than naming files, so a workflow added later is covered the day it lands — that is the part that stops this recurring. Both are renamed from test_changed_workflows_* to test_every_workflow_*, since the old names would now be wrong. Three guards are added or widened:

• every workflow declares permissions:, and no permissions: value anywhere is write-all — including job-level blocks, which override the workflow-level one;
• action pinning now also covers job-level uses:, i.e. reusable workflows, which have no steps list for the step-level walk to reach;
• publish-docs.yml never hardcodes the Fern CLI version again.

Granular write scopes (contents: write and friends) are deliberately still allowed — a release workflow will legitimately need one. The invariant is that the scope is declared and never blanket.

The guards are not vacuous

Against the workflows as they stood before the first commit, three fail:

FAILED test_every_workflow_pins_every_action_to_a_commit
FAILED test_every_workflow_does_not_persist_checkout_credentials
FAILED test_every_workflow_declares_least_privilege_permissions

And against a probe workflow that declares permissions: contents: read at the top, escalates one job to permissions: write-all, and references a reusable workflow at @main, two fail. Before the last commit that same probe passed all thirteen — which is how those two holes were found.

One thing to decide knowingly

publish-docs.yml is the only workflow that never runs on a pull request — it is push to main only, gated on github.run_number > 1. So the persist-credentials: false change on the publish path cannot be exercised before merge. fern generate --docs authenticates to Fern with FERN_TOKEN rather than over git, so this should be inert, but you know Fern's internals better than I do. If you would rather land the rest first and that line separately, say so and I will split it.

Verification

• I am familiar with the Contributing Guidelines
• Added or updated focused tests
• Updated documentation for user-visible changes — n/a, no user-visible behaviour changes
• Ran make lint — All checks passed! (also ruff check . as CI runs it)
• Ran make test — 5460 passed, 18 skipped
• Ran make build — built the sdist and wheel
• Did not add credentials, private datasets, or proprietary benchmark content

Also ran the two CI-only gates: scripts/check_oss_boundary.py (passed) and scripts/ci/check_public_benchmarks.py --require-files tests/golden (passed, 2 files). Python 3.13.12, macOS 15 (arm64), uv sync --extra all --extra dev.

Release Impact

• No user-visible release note needed
• Updated CHANGELOG.md

[rng1995]

[P2] Allow same-commit local uses references. GitHub local actions and local reusable workflows use the supported ./... syntax without an at-ref and execute from the caller's commit. Because the helper now includes both step- and job-level references, this assertion rejects both forms even though no remote revision can float. Exempt validated local paths before requiring a 40-character SHA for external actions.

[rng1995]

[P1] Lock the dependency tree before the secret-bearing step. fern-api 5.66.1 still has an unshrinkwrapped optional dependency on @boundaryml/baml with a semver range; BAML accepts @scarf/scarf 1.x, whose currently resolved package runs a postinstall script. This still resolves and executes mutable lifecycle code immediately before the global Fern process runs with FERN_TOKEN. Use a committed lockfile with npm ci and npx --no-install, or omit optional dependencies and lifecycle scripts if docs publishing does not need them.

[rng1995]

The workflow hardening improves action pinning and token scope, but the Fern installation still executes an unlocked transitive lifecycle script immediately before the secret-bearing publish step, and the new global guard rejects supported local action and reusable-workflow references. Workflow tests passed (13 tests), and both updated action SHAs match their official tags. Requesting changes for the two remaining hardening gaps noted inline.

[dberzan]

Thanks — both were right, and testing the P1 fix instead of assuming it turned up a second problem in my own patch. I've gone with your first option, the lockfile.

P1 — lifecycle scripts

Confirmed the chain against the registry before changing anything:

fern-api@5.66.1              scripts: {}   hasShrinkwrap: false
  └─ optionalDependencies:   @boundaryml/baml  ^0.219.0
       └─ dependencies:      @scarf/scarf      ^1.3.0      → 1.4.0
            └─ scripts.postinstall: "node ./report.js"

My earlier commit said pinning the version stopped the tree floating. That was wrong — npm re-resolves every transitive edge from semver on each run.

The first fix was also wrong, in a way worth flagging: --omit=optional is silently ignored for a --global install. Installing fern-api@5.66.1 globally with and without the flag produces identical trees — @scarf/scarf and its postinstall land either way. Reproduced on npm 10.9.9 (what setup-node 22 ships) and 11.12.1. It only takes effect for a local install. So the patch you were reading claimed a property it didn't have.

Now: fern/package.json and fern/package-lock.json are committed, and both workflows run

npm ci --prefix fern --ignore-scripts --omit=optional
./fern/node_modules/.bin/fern <check|generate --docs>

That closes both halves of what you wrote. It no longer resolves: every package in the lock carries an exact version and an integrity hash, so a compromised republish can't substitute. It no longer executes: --ignore-scripts, and with npm ci being a local install --omit=optional now genuinely applies, leaving fern-api alone in the tree. Calling the binary by path rather than PATH closes the substitution gap too.

Verified end to end rather than reasoned about: the exact command sequence installs one package, and fern check reports 0 errors against this repo. That also settles the question I couldn't answer before — docs validation does not need @boundaryml/baml.

Two notes on the shape, both reversible if you'd rather:

• The lock adds a second home for the CLI version alongside fern/fern.config.json. A guard asserts package.json, package-lock.json and fern.config.json all agree, so they can't drift — that was the failure this PR already fixed once and I didn't want to reintroduce it.
• node_modules/ is now in .gitignore; it wasn't before.

P2 — local references

Agreed. uses: ./... skips the SHA requirement after validating the path doesn't escape the repo. Two edges worth naming:

• My first version exempted ./.github/actions/build@main — ./-prefixed but carrying an @ref, which isn't local syntax. Fixed; a ./ reference with an @ falls through to the SHA check.
• docker:// is deliberately not exempted. A container tag is mutable, so rejecting it is intended, not an oversight.

Also in here

• ci.yml's docs lane got the same install. Not really optional: the new guard covers every workflow, and a guard with a carve-out for one file isn't the guard I want. Its exposure is smaller — no secret, contents: read — but it's the same command.
• docs/README.md, docs/AGENTS.md, docs/developer-guide.mdx told contributors to run the unpinned global install. They now use the same lockfile install.
• test_every_workflow_declares_least_privilege_permissions → test_every_workflow_declares_explicit_permissions. It only rejects write-all and a missing block, not every broad grant — a granular contents: write is legitimate for a release workflow. The name promised more than the assertion delivered; the assertion is unchanged.

Say the word on any of these and I'll drop them.

Verification

ruff check . clean, 5463 passed, 18 skipped, make build succeeds, plus the two gates that live only in ci.yml — check_oss_boundary.py and check_public_benchmarks.py --require-files tests/golden. Every new or relaxed guard was checked against a throwaway probe: reverting ci.yml to npm install --global fails two of them, and changing fern.config.json's version alone fails the drift guard. Probes aren't committed.