--- name: ci-design description: Vocabulary and principles for well-designed CI. Use when the user wants to design, review, or audit CI, says CI is noisy, slow, or expensive, or is designing a workflow yml. ---

# CI Design

Design CI so cost tracks the surface area actually touched, not the number of pushes. Use this language wherever CI is being designed, reviewed, or audited.

## Priorities

Fix in this order — each tier assumes the ones above it are already sound:

1. **Minutes and billing waste.** Runner tier, caching, unconditional jobs. Money leaks here even when every run is green. 2. **PR feedback latency.** How long a contributor waits to learn a push is good or bad. Concurrency and trigger surface live here. 3. **Run and notification volume.** Duplicate or invisible checks, noisy scheduling. Annoying, but cheaper than the first two.

Baseline failure noise (a flaky test, a known-red job) matters less than any of these — it's visible and locally fixable. Structural waste isn't; it compounds silently across every run.

## Vocabulary

Use these terms exactly.

**Trigger surface** — the product of events, branches, and paths that fire a workflow (`on: push/pull_request` × branch filters × path filters). The trigger surface is the first lever: a workflow that fires on every push to every branch has a trigger surface many times larger than the work it actually needs to validate.

**Path filtering** — restricting a job to run only when files it cares about changed. The required-checks-safe pattern: never put `paths:` at the workflow level on a job that's a required status check — GitHub can leave a required check permanently pending if its workflow never triggers. Instead, filter *inside* the job with a paths-filter step that gates the real work, so the workflow still runs and reports green (or explicitly skipped) on every PR.

**Concurrency group** — a `concurrency:` key that cancels superseded runs on the same branch/PR (`cancel-in-progress: true`), so a burst of pushes collapses to one live run instead of a growing queue. Release and deploy paths are the deliberate exception: don't cancel a run that's mid-deploy just because a new commit landed.

**Caching** — persisting dependencies or toolchains across runs, keyed on something that changes only when the cache should invalidate (a lockfile hash, a pinned tool version). The sin isn't the absence of a cache line — it's reinstalling a toolchain, browser binary, or dependency tree from scratch on every single run when the inputs didn't change.

**Runner cost tiers** — macOS runners cost several times what Linux runners cost per minute; Windows sits in between. A job earns a pricier runner only by a real platform dependency (building a macOS binary, testing an Xcode-only path) — never by inertia or a single assumption (like a temp path) that's trivially fixable on Linux.

**Scheduled scans** — expensive or slow analysis (security scanning, full matrix builds) that doesn't need to gate every PR. When merge velocity is high, put it on a schedule plus main-branch pushes instead of every pull request — it still runs regularly, just not once per push.

**Iteration burst** — a string of pushes to the same branch in quick succession, each firing its own run. Expected during active development, not itself a problem. The concurrency group is what determines whether a burst turns into cancellations (cheap, correct) or a queue of runs that finish stale and red (expensive, misleading).

**Invisible checks** — status checks that show up on a PR with no corresponding yml in the repo, most commonly GitHub's CodeQL default setup configured through repo settings rather than a workflow file. They can't be inventoried, diffed, or reviewed by reading the repo. Export them to a checked-in workflow so every check the repo runs is visible from its files.

## Principles

- **Every job answers "which changed files require me?"** If a job can't name the files that would make it necessary, its trigger surface is too wide. - **Every workflow has exactly one visible definition on disk.** No check should exist that isn't traceable to a yml file in the repo. - **Cost scales with touched surface area, not PR volume.** Ten pushes that touch nothing relevant should cost less than one push that touches everything. - **CI is a signal.** A check that's red mid-iteration by design — because nothing cancelled it, because it always runs even on draft churn — trains people to ignore red, which erodes the signal for the run that matters.

## Going deeper

- **Running an audit** — see [references/AUDIT-PLAYBOOK.md](references/AUDIT-PLAYBOOK.md): the repeatable procedure for inventorying, measuring, and ranking CI findings across one or more repos.