The OSBR Handbook
Sign in

CI/CD Pipeline

This is the standard for how a change travels from a developer's machine to production at OSBR. It expands the CI/CD stance the Infrastructure Planning Policy states — deploy from the reviewed main line, at dev/prod parity, measured with DORA — into a working pipeline: three gates, what each one owns, and where the authoritative pass/fail is decided. It is the delivery half of the story the Testing Standards tell about where tests run (§3-12); read the two together. Deviations are allowed, but — as everywhere in the handbook — they must be deliberate and justified in the project's design notes.

The pipeline is where OSBR's values stop being aspirations and become machine enforcement. Be Nice: the same script an engineer runs locally is the script CI runs, so the pipeline is legible — nobody has to reverse-engineer a bespoke CI config to know what "green" means. Be Kind: the release gate is enforced by the machine, not by any one operator's diligence, so no teammate carries the release on their personal care and no colleague inherits a break because someone was tired on a Friday. Be Strong: the gate runs against a real production-simulation, on a fixed architecture, so it finds the environment- and architecture-dependent failure before a user does — not the tautology of a check that only passes because it never touched anything real.

How to read this policy

1. Goal

The goal of the pipeline at OSBR is the same change, the same result — fast where feedback can be fast, and authoritative where correctness must be decided. Concretely, an engineer who picks up a task produces the same result regardless of host OS (PC / Mac) or CPU architecture (x86 / ARM), and no change reaches production until it has passed authoritatively in a production-simulation environment. Three properties define success:

A gate that does not move one of these properties is waste. We optimise for a trustworthy release, not for a fast pipeline that lets the wrong thing through.

2. Responsibility

The pipeline runs in three gates, each a prerequisite of the next. Every engineer owns getting their change through all three; the gates are shared infrastructure and their health is a team-level signal, never an individual rating — the same way the DORA metrics are read in the Infrastructure Planning Policy.

2-1. Local — fast, environment-agnostic feedback (not a production simulation)

On the engineer's own machine, run the environment-agnostic checks only: domain logic, type-checking, unit tests, lint. These fail the same way on any host, so they belong where feedback is fastest. Local MUST NOT be relied on to stand up production-like infrastructure — it stays light so the inner loop stays in seconds. Local green means "my logic and types are correct," and nothing more. It is the same environment-agnostic inner loop the Testing Standards require of small tests (§3-3, §3-12).

2-2. CI — the production-simulation environment (the authoritative gate)

CI is the production simulation, and it is the single authoritative result. It MUST run centrally on one canonical architecture, from the same container images as production, with:

Integration and end-to-end tests run here, not locally — this is where environment- and architecture-dependent failures surface: native binaries (x86 vs ARM), integration with real dependencies, config and secret wiring, networking, managed-service behaviour, timing and concurrency. A change MUST NOT merge until CI is green, and CI's fixed architecture means x86-vs-ARM differences never produce two "official" answers.

2-3. CD — deploy, only after CI is green

On merge to main / release, CD deploys. It MUST run only after the CI production-simulation gate is green — never before. CD runs the reproducible deploy script (scripts/deploy.sh), uses progressive delivery (canary / blue-green), and verifies production responses online after the release — a failed post-release verification is a failed release. Credentials are passed only at runtime.

3. Practices

3-1. Determinism across host and architecture

The whole point of the pipeline is that the machine, not the machine's owner, decides correctness. That requires the run to be reproducible byte-for-byte.

3-2. One set of scripts across all three gates

Consolidate the pipeline into runnable scripts (e.g. scripts/ci.sh, scripts/deploy.sh) that Local, CI, and CD all invoke — never reimplement inline. What an engineer runs locally MUST be the same command CI runs. This is the Be Nice rule for the pipeline: the checks are legible because they live in the repo as plain scripts, not scattered across a CI platform's bespoke configuration.

3-3. Two classes of error, two loops

Where a check runs follows from what class of error it catches:

Error class Examples Caught at
Environment/arch-agnostic domain logic, types, unit, lint Local (fast)
Environment/arch-dependent integration, native binaries (x86/ARM), config/secret wiring, networking, managed-service behaviour, timing/concurrency CI production-simulation (authoritative)

Local green is never taken as proof that production will work — that is the CI production-simulation gate's job. Pushing an environment-dependent check down into the local loop only makes the loop slow and the result unreliable; pushing an agnostic check up into CI only makes feedback slower. Each check belongs in the loop that matches its error class.

3-4. Secrets and config are injected, never committed

3-5. Managed services are emulated or ephemeral in CI

Integration against real dependencies is where belief meets reality, so CI must provide something real enough to break against — without depending on a shared, long-lived environment.

3-6. Deploy is progressive and verified online

A green CI gate says the change is correct in simulation; it does not by itself prove the change is healthy in production. CD closes that last gap.

3-7. The gate is machine-enforced, not operator-trusted

3-8. Acceptance criterion

An engineer, on any OS / architecture, runs the same container and the same script and gets a byte-identical build and the same agnostic-test result locally; the authoritative pass/fail for environment- and architecture-dependent behaviour is decided by the CI production-simulation environment on the fixed canonical architecture; and CD deploys only after that gate is green, verifying production online before the release is called done.

References

Delivery practice & metrics

Techniques & tooling

Related OSBR standards