Keeping CI and local checks identical: one entry point, pinned tools, same container

Goal

A check that passes locally passes in CI and the other way round, so that "fix lint" commits, CI-only failures and "it works here" disputes disappear, and an agent can trust its local run as a prediction of the pipeline.

Prerequisites

A task runner entry point for each check (see the related article), a version manifest for the toolchain, and a CI service that can run a container image of your choosing. GitHub Actions documents running a job's steps inside a container declared with container: and an image:; asdf reads tool versions from a .tool-versions file and installs everything listed with asdf install; mise reads the same file or a mise.toml with a [tools] section.

Steps

1. Define every check once as a named task (lint, typecheck, test, build) and make the CI workflow call those names and nothing else. Where CI needs different behaviour (no watch mode, machine-readable output), add a flag the task accepts rather than a second command.
2. Pin the toolchain in a manifest committed to the repository (.tool-versions, mise.toml, or the dev container's Dockerfile) and have both the local bootstrap and the CI job install from it; never latest.
3. Run CI inside the same container image the dev environment uses, or build the image in CI from the same Dockerfile, so operating-system packages match too.
4. Pin the tools that perform the checks (formatter, linter, test runner) in the project's lock file rather than as global installs, and invoke them through the task so the locked version is the only one that can run.
5. Remove environmental differences: avoid code paths that behave differently when a CI variable is set, fix locale and timezone inside the task (LC_ALL=C.UTF-8, TZ=UTC), and make caches optional inputs rather than requirements.
6. Add one scheduled job that runs the full check set from a clean clone in the container without any cache; it catches checks that pass locally only because of leftover state.
7. When CI fails and local passes, treat the difference as the bug: record the discrepancy (version, environment variable, missing file) and eliminate it before fixing the symptom.

Expected result

The workflow file is short: check out, install from the manifest, run the named tasks. A contributor reproduces any CI failure with the same command name, and CI time goes to the checks rather than to setup drift.

Limits and test basis

Hardware-dependent behaviour (CPU count, memory limits, GPU) still differs and shows up in timing-sensitive tests. Secrets and service credentials differ by design; checks that need them belong outside the parity set. This is a proposed procedure built on the cited documentation; no defect-rate figures are claimed.

Run the checks in CI mode on both sides

Many tools already change behaviour when the CI environment variable is set: test runners stop writing new snapshots and disable watch mode, package managers refuse to modify the lockfile, and scaffolded test configurations forbid focused tests. Those branches cannot be removed, so the parity rule is the reverse of avoiding them: the task that runs the check set exports CI=true itself, so the local run and the pipeline take the same branches in every third-party tool. The project's own code should not branch on CI at all. A check that passes without the variable and fails with it is then reproducible locally with the same command.