How to automate monorepo dependency upgrades without breaking CI.

why · batched · upgrades · break · ci

Why batched dependency upgrades break CI in a monorepo.

A weekly Dependabot batch in a monorepo opens between forty and a hundred PRs on a single window — a long-tail of lockfile bumps and lockfile-wide transitive reshuffles. The CI matrix takes the same wall-clock time per green path, but a single failing test in the matrix flips every batched PR the same red. Reviewers cannot tell which of the forty open reds is the one that mattered, and the merge queue stalls or, worse, merges the wrong diff because the same red is showing on the unrelated bump. The pipeline is technically working; the question it cannot answer is which of the failing tests is the one a regulator will read out of the audit binder three quarters later. That gap is the audit-trail gap, and it is not closed by tweaking cron schedules or by capping batch size — it is closed by ordering the failing-test replay ahead of the diff.

read · the · trigger · path · first

Read the trigger path first. Replay the failing test before the diff lands.

A Driftlock run starts by reading the failing test out of the CI log before the dependency upgrade diff ever lands. The matrix is tiered — the failing regression runs first, the unit suite runs second, the integration suite runs third, and the e2e matrix runs only on incident or CVE-class signals. The order is the same every time regardless of the trigger source, because the failing-test-first ordering is the seam a regulator replays later. A CVE-triggered upgrade and a flaky-test-triggered upgrade both run the same failing-test path; only the e2e tier is added when the trigger class is high. The watch is the same watch, the sandbox is the same sandbox, and the ordering is the ordering any review board reads.

hermetic · sandbox · is · the · replay · boundary

The hermetic sandbox is the reproduceable boundary.

The dependency-upgrade run executes inside the hermetic Nix / Bazel sandbox the architecture page documents. The sandbox mounts the same toolchain your CI already uses and a topology-aware test cache that only re-runs the trigger path; the rest of the matrix stays warm. The same diff byte-for-byte on rerun, the same test result byte-for-byte on rerun, and the same CycloneDX SBOM byte-for-byte on rerun: a reviewer who signs off on the diff is signing off on the diff the auditor replays. The same posture carries to the air-gapped offline runner on the Enterprise tier — the sandbox is identity-stable, not network-dependent. The replays land on /architecture#pipeline-sandbox-isolation so the reader can read the sandbox boundary side by side with the hermetic-build hash that pins it.

signature · is · the · pr · identity

The signature is the PR identity. Cosign over (commit_sha || sbom_sha256).

Once the test matrix is green, the sandbox signs the resulting commit with ed25519 over the compound claim (commit_sha || sbom_sha256), using a cosign-keyful keypair that lives in your KMS. The keypair rotates on your schedule and verifies in the GitHub UI without an extra plugin — a reviewer can confirm the commit, the SBOM, and the signer in one click. The signing claim is two-part on purpose: commit_sha pins the source, sbom_sha256 pins the supply-chain artefact, and any drift between the two cannot pass the signature. The SBOM the same run emits is the artefact the reviewer sees on the diff; the ledger row the same run writes is the row the regulator replays months later. The signature is the audit-trail row collated to single bytes.

where · this · lands

Where this lands — the connector list and the key custody.

The set of connectors the watcher reads from — GitHub, the CI identity, the on-call alerting surface, and the dependency advisory feeds — is enumerated on /integrations, with each row linking to the matching anchor on /architecture / /docs / /security where the reader can deep-link. The signing key in the customer KMS, and the sandbox posture itself, are documented on /security, with the same vocabulary the architecture page uses. The pair closes the audit-trail bar my opening post argues is the only bar a regulated monorepo platform lead should accept — a per-PR row a regulator can replay, a signature over the commit that survives a key rotation, and an SBOM document a downstream compliance tool can ingest.

• Connectors the watcher readsEach surface — GitHub App, CI identity, PagerDuty, NVD/GHSA/OSV — paired with the /architecture pillar it ties to, so a reviewer cross-checking the PR lands on the same vocabulary the platform team wrote it in.
• Sandbox boundary = replay boundarySame toolchain, same cache, same diff byte-for-byte on rerun. Hermetic-build hash pins the run, and the auditor replays the run by id, not by the customer tooling.
• Signing claim is two-part on purposeed25519 over (commit_sha || sbom_sha256) — commit pins the source, sbom_sha256 pins the supply-chain artefact, drift between the two cannot pass the signature.
• Keys live in your KMS, rotate on your clockNo vendor-KMS key, no unknown-public-key trust store. The signing key the regulator replays is the same key the platform team rotates, on the schedule the customer sets.