Skip to main content
Make is the developer-facing command surface. Cargo is the default backend. BuildBuddy/Bazel is an opt-in acceleration backend for developers with BuildBuddy access and for owner-selected release validation and Linux/macOS binary packaging. GitHub Actions CI runs on GitHub-hosted runners through the Cargo lane; the former GCP BuildBuddy CI fleet was retired on 2026-07-03.

​
Local Commands

Use these commands for normal development:
Avoid raw cargo for normal repo work. When you need targeted Cargo commands, use ./scripts/repo-cargo so output roots and multi-agent work stay isolated.

​
BuildBuddy Opt-In

Set MEERKAT_BUILDBUDDY=1 to route the same Make lanes through the BuildBuddy backend:
Use BUILDBUDDY_DRY_RUN=1 with explicit BuildBuddy Make targets to inspect the selected command without running it. The explicit targets are make buildbuddy-build, make buildbuddy-check, make buildbuddy-clippy, make buildbuddy-test, make buildbuddy-test-unit, make buildbuddy-test-int, make buildbuddy-e2e-fast, and make buildbuddy-e2e-system. The live-provider targets are make buildbuddy-e2e-live and make buildbuddy-e2e-smoke when credentials are configured. The Make targets delegate through scripts/run-build-backend-lane; when BuildBuddy is enabled, that switch calls scripts/buildbuddy-dev.

​
Test Lanes

The canonical e2e lane taxonomy lives in tests/integration/src/e2e_lanes.rs. Scripts and BuildBuddy targets route to that taxonomy rather than inventing separate lane names. The dense Mob topology stress has a dedicated GitHub-hosted Linux workflow, .github/workflows/mob-dense-topology.yml. The active top-level CI calls it and requires its result alongside BuildBuddy, while the full Cargo workflow also runs it from the existing unit-test archive and includes it in the Cargo gate. The test owns a five-minute wire-materialization budget; its nextest profile reports the named test every minute and terminates a whole-test stall after eight minutes. The result is bounded to the hosted runner environment: local macOS and BuildBuddy runs are supplementary evidence, not latency predictions or substitutes for this lane.

​
Architecture Gates

Machine and surface contracts have direct Make targets:
These gates protect generated schemas, SDK wrappers, machine artifacts, and runtime authority invariants. make machine-verify is the bounded TLC lane used for normal validation. Use make machine-verify-full only when you deliberately need the unbounded verification set.

​
CI Shape

GitHub Actions runs one reusable Cargo workflow for pull requests and ordinary pushes. Its current per-push shape is:
  • change classification, formatting and governance, lock consistency, and workspace clippy
  • one prebuilt unit-test archive consumed by eight unit shards
  • prebuilt integration archives consumed by mob, everything-else, and remaining crate groups
  • deterministic e2e-fast, generation ratchets, and bounded machine verification
  • WASM checks, with the browser contract and full Web SDK lane path-gated to relevant changes
  • host Python and TypeScript SDK suites plus dependency audit
  • one aggregate Cargo gate, followed by the top-level CI gate
Docs-only changes skip code build and test work, but governance still runs. Machine-authority paths are classified fail-closed so a classifier miss cannot silently skip machine verification. The final top-level gate emits a small attestation that binds a successful main push to the exact commit SHA, Git tree SHA, workflow run, and workflow attempt. Attestations are not emitted for pull requests or failed runs.

​
CI Retry And Concurrency

Pull request CI uses one concurrency group per PR with cancel-in-progress: true. Starting another PR-associated attempt in that group automatically cancels the older in-progress attempt, even when nobody issues an explicit cancel command. Because the aggregate Cargo and top-level CI gates run with always(), the cancelled attempt can then publish fresh failed gate contexts during teardown. Treat check-context precedence as part of retry recovery:
  1. Preserve the reviewed head commit when approvals or downstream evidence are bound to its exact bytes.
  2. Compare the active step and elapsed time with a successful exact-head run before classifying a slow job as hung.
  3. When a new PR-associated attempt is necessary, expect the automatic cancellation residue. The recovery attempt must reach both aggregate gates in the check suite it is repairing.
  4. Inspect every check suite on the reviewed head that publishes the required GHA Cargo / Cargo lane gate or CI gate context. A green shard or successful manual workflow is useful evidence, but it does not clear a failed required context in another suite on the same head.
Do not infer mergeability from a workflow’s overall conclusion alone, and do not apply a creation-time or completion-time recency rule to suites on the same head. In the observed recovery, auto-merge remained blocked after the newest of three suites reported a successful CI gate; it fired only after the last remaining suite reported that context successful. Treat each suite that publishes a required context as independent recovery evidence, because neither the newest nor the latest-completed result was observed to supersede the others. In this recovery, gh pr checks reported pass while guarded merge remained blocked, so an attempted merge that stays blocked is stronger evidence than that flattened view. Inspect the suite records directly when the rollup and merge policy disagree:

​
Nightly Lanes

Expensive or low-churn coverage runs daily and on demand on GitHub-hosted runners:
  • clippy across all targets and all features
  • feature-matrix lint and tests
  • minimal-feature and surface-modularity tests
  • e2e-system
  • the full Web SDK and WASM browser contract suites
  • release packaging dry-runs
  • security audit
The tag release workflow consumes that exact-tree attestation instead of re-running the same validation suite. It still builds and publishes the platform-specific release artifacts from the attested source. Manual recovery dispatches retain the explicit release-validation lanes because old release commits may predate attestation artifacts. The repository pre-push dispatcher follows the same identity rule. A complete successful hook run writes a local Git-tree-keyed evidence stamp. A later push of the identical tree, including its release tag, validates the pushed object and checked-out HEAD identity and then reuses the complete gate result. BuildBuddy remains an opt-in developer and owner-selected release validation or binary packaging backend. The former CI control-plane workflow at .github/workflows/buildbuddy.yml is workflow_call-only and has no caller, so it is inert and is not a fleet that CI starts automatically. Release validation and packaging use explicit BuildBuddy actions when selected by the owner; Windows packaging and registry publication remain GitHub-hosted.

​
Doctor

Run:
The doctor checks the API key, pinned bb CLI, generated Bazel files, selector behavior, lane isolation, and docs wiring without printing secrets.

​
Multi-Agent Work

Separate Git worktrees are already isolated by path hash. If multiple agents share one checkout, set a distinct RUST_LANE_ID per agent when you want stable warm local output roots.

​
See Also