CI for a busy monorepo

#What goes wrong at scale

#The configuration

// build.sbt, on the root project

// 1. Cache: nothing to set. The builtin test owns the LocalDir build snapshot and saves once per run;
//    every other job restores it.

// 2. Coverage in its own workflow: nightly, on demand, and on a PR labeled coverage.
zipxCoverageWorkflow := Some(
  Coverage.workflow(
    CoverageTrigger.Scheduled(Cron.daily(hour = 3)),
    CoverageTrigger.Dispatch,
    CoverageTrigger.prLabel("coverage"),
  )
)

// 3. Images and deploys run from a dispatched zipx-deploy.yml, never on a merge.
zipxDeployTrigger := DeployTrigger.Manual()

zipxCapabilities ++= Seq(
  Capability.dockerGraph.copy(gate = Gate.Always),
  zipxTasks.deployGraph(
    participates = _.docker,
    command = promote,
    targets = _ => List(
      Target(TargetName("stg"), environment = Some("staging"), group = Some(TargetGroup("pre-prod"))),
      Target(TargetName("prod"), environment = Some("production")),
    ),
    gate = Gate.Always,
  ),
  // 4. The builtin test is already affected-scoped on PRs. A Once job whose inputs the classpath graph
  //    cannot see names the modules it tests.
  zipxTasks
    .once(name = CapabilityName("image-it"), command = imageIt / testFull, phase = Phase.Verify, gate = Gate.Always)
    .withAffectedBy(_.docker),
)

// On each image module: the references the deploy workflow checks before pushing.
zipxImageRefs := (Docker / dockerAliases).value.map(_.toString)

zipxWorkflowGenerate then writes three workflows. Rendered live from the planner for a three-module build (schema, api, and a service image):

{
      val ci     = Planner.plan(libGraph, split.ci, config)
      val deploy = DeployWorkflow.plan(libGraph, split.deploy, config, DeployTrigger.Manual())
      val cov    = CoverageWorkflow.plan(coverage, config)
      s"""|ci.yml:            ${ci.jobs.keys.mkString(", ")}
zipx-coverage.yml: ${cov.jobs.keys.mkString(", ")}
zipx-deploy.yml:   ${deploy.jobs.keys.mkString(", ")}""".stripMargin
    }

ci.yml:            affected, test, image-it, verify
zipx-coverage.yml: coverage
zipx-deploy.yml:   resolve, docker-service, deploy-service-prod, deploy-service-stg

ci.yml keeps what gates a merge: test, image-it, and the affected job image-it reads. The image and its deploys moved to zipx-deploy.yml, behind a resolve job that plans each dispatch. Coverage is one job in zipx-coverage.yml. Generate refuses the shapes that would break this: coverage that replaces test or saves the cache, and a deploy the dispatched workflow could not run (see Validation).

#What a PR, a merge, and a deploy run

On a PR, test diffs against the PR base and runs the test tasks of the changed modules and their dependents, as one parallel all command. A Once job with withAffectedBy runs only when one of its modules is in that set. A diff that cannot run tests everything. The PR's first push restores main's snapshot; later pushes restore the PR's own.

On a merge, cache-rehydrate compiles main and saves the snapshot the next PRs restore. Nothing ships.

On a dispatch, resolve reads each Environment's deployments from GitHub and diffs each module's last deployed commit against the one being deployed. The image jobs push only tags a registry lacks. Each deploy job binds its Environment, so approvals still apply, and records the module and commit it shipped for the next changed deploy. Deploys to one target queue behind each other and are never cancelled.

#Measured

Each row is one lab scenario on 0.11.0, then on a snapshot of the change that fixed it. Run ids are in the lab repository's Actions tab and its README.

#Adopting it

In order, one PR each, so each step's effect on required checks is visible on its own.

1. Upgrade. test becomes affected-scoped on PRs with no setting. Its check name stays test. A build that replaces test by name keeps its own command.

2. Coverage. If coverage replaced test (Coverage.once(name = Capability.TestName)), generate now refuses it. Set zipxCoverageWorkflow, drop the capability, and remove coverage from the required checks if it was there.

3. Deploys. Set zipxDeployTrigger := DeployTrigger.Manual() (every deploy a dispatch), or DeployTrigger.staged(deployLabel, skipLabel) (staging on every merge and on labeled PRs, production by dispatch), and regenerate. Generate names each fix it needs: drop push-only conditions such as onMainPush, give every deploy target an Environment, keep image and deploy capabilities Graph-scoped, and under Staged mark the staging targets DeployStage.PreProduction. Set zipxImageRefs on image modules, tag images from ZIPX_DEPLOY_SHA before GITHUB_SHA, and give each tier a Target.group if you deploy several targets at once. Give each production Environment a deployment branch policy on the default branch.

4. Integration jobs. Add withAffectedBy to each Once job whose inputs the classpath graph cannot see.

5. Check the output. zipxWorkflowCheck in CI keeps the committed workflows honest; actionlint in the repo root catches anything GitHub would reject before a push does.

#Limits

• An edit to a shared helper or bare setting in build.sbt, or to any file under project/ other than the catalog, affects every module. An edit inside one project's definition affects that project, and a catalog bump the modules that declare the library (see Affected).

• zipxTestAffected scopes the builtin test only. A user Aggregate capability with per-module commands still runs all of them.

• Registry-style steps that need an image (LaunchPad, a manifest registry) run whenever their module's image is in the deploy plan, including when its tag already existed, so they must be idempotent.