Skip to content

Roll out across an organisation

This page covers cortexbuild rollout, which runs CortexBuild across many repositories at once, and the governance audit log every governance action writes to.

Governance audit log

An append-only log records governance events -- adopting, overriding, syncing, promoting, upgrading, and rolling out -- for each repository. It lives at .cortexbuild/audit-log.yaml (one per repo) and is separate from the recurrence ledger, which tracks classes of recurring issues rather than individual events.

The log is safe under concurrent writes (parallel runs never lose or corrupt entries), re-running the same action is a safe no-op rather than a duplicate, it never records a timestamp or personal data, and older or newer versions of the file still parse correctly.

cortexbuild rollout

Runs CortexBuild's passes across a list or glob of repositories and produces one combined report.

# Dry-run (read-only) across child repos of ./org
cortexbuild rollout --base ./org

# Apply the mutating passes (adopt + standards sync) to selected repos
cortexbuild rollout --base ./org --glob 'team-*' --apply --json

What makes this safe to run across many repos

  • Each repository is isolated. A failure in one repository is recorded and the rest of the batch continues; it never stops or corrupts the whole run.
  • Mutating changes are opt-in. By default, rollout only reads and reports; nothing changes until you pass --apply. Before making a change, each target's governance state is captured so it can be restored if something goes wrong, so a repository is never left half-updated.
  • Safe to point at a large tree. Common directories that should never be scanned (dependency folders, virtual environments, nested repositories) are excluded automatically, and a repository limit keeps a very large glob from running away.
  • Monorepo-aware. A repository containing multiple services is handled as its services, not double-counted as the parent directory too.
  • Fully offline and deterministic. No data leaves your machine, and running it twice against the same set of repositories produces the same report.
  • Audited. Each rollout records an event in the audit log described above.