ci-pipeline-and-gates

CI Pipeline & Gates

A CI gate is not a decorative green check — it converts one release-blocking contract into a check a build either passes or fails, without trusting a human. Keep the pipeline lean: one workflow file for most single-package apps, every job pinned, every gate traceable to a named contract, and an honest note wherever CI cannot prove the thing that actually matters.

Read the reference for the task at hand:

• references/workflow-skeleton.md — the copy-paste single-file ci.yml: pinned runner + toolchain, freshness gates, format/analyze, randomized tests, host-sqlite, coverage-strip, and the release-build job.
• references/policy-grep-gate.md — the grep-based invariant gate: the three-criteria bar, strip-comments-first, anchor-to-structure, accumulate-and-fail-once, write-the-reason-for-a-stranger.

Run scripts/ci-gates.sh and scripts/banned-strings.sh before a PR to reproduce the static gates locally.

Non-negotiable rules

1. Every gate maps to exactly one named contract — name it. A check that serves no stated contract is not a gate: make it advisory and say so, or don't add it. Never invent a merge-blocker with nothing behind it. This keeps the pipeline auditable and stops gate-sprawl.
2. Pin the runner AND the toolchain on every job. runs-on: ubuntu-24.04 (never -latest — image drift moves lcov/toolchain versions with no diff to review) and subosito/flutter-action@v2 with an explicit flutter-version or flutter-version-file, channel: stable. A floating SDK silently re-renders goldens and perturbs determinism. Bump the version only in a dedicated PR.
3. Mark unverified action versions inline; never invent a major. A wrong major silently fails or silently changes behaviour. Write # VERIFY: next to a version you haven't confirmed rather than guessing @v7.
4. Format and analyze are hard gates. dart format --output=none --set-exit-if-changed . and flutter analyze --fatal-infos. --fatal-infos is load-bearing: an info left unfixed is a warning that gets ignored next. See lint-and-style-config.
5. Codegen and schema are freshness gates, not build steps. Run the generator, then git diff --exit-code the outputs; a nonzero diff fails with a message telling the author to regenerate and commit. This is the entire mitigation for committing generated code, and the one gate that catches "changed the schema, forgot to migrate". See run-codegen, run-migration.
6. Randomize test ordering; provision native deps the test host needs. flutter test --test-randomize-ordering-seed random is free detection of inter-test state leakage. On Linux, flutter test runs in a plain Dart VM where sqlite3_flutter_libs does nothing — install host sqlite3 before a suite that opens a real DB, or it fails for a reason that looks like a broken repo.
7. Static greps catch what runtime can't — held to the three-criteria bar. A grep-based gate is legitimate only when the invariant is textually decidable, silent when broken, and one line to break (references/policy-grep-gate.md). It proves properties of the source graph a passing test never can (an import that isn't reached at runtime, a manifest attribute). Two out of three criteria means code review, not a grep.
8. Coverage is a published report, never a gate. No percentage threshold, no paid service. A covered line that asserts nothing is worthless. First fix the upward lie: flutter test --coverage omits files no test imports, so an untested file scores zero denominator lines, not 0% — one tested file can report ~100%. Include untested files, then strip generated code from lcov.info. See testing-strategy.
9. Gates verify, they never bless or mutate the repo. No --update-goldens, no dart format --fix, no committing regenerated code from CI — a gate that fixes the thing it checks asserts nothing. Regeneration is a local, human-reviewed act. Goldens run on the pinned runner and CI only compares. See widget-golden-and-a11y-testing.
10. A red gate blocks; be honest about the limits. Never continue-on-error: true on a gate, never merge on a skipped gate, never // ignore: a static finding. And state plainly what CI cannot prove — audio output, real-font rendering, true on-device behaviour — so the manual on-device pass is treated as a load-bearing release artifact, not a chore.