Everything as Code

Authoritative Version-Controlled Definitions

Summary

Source code and the definitions that determine system state live in version control as the authoritative record.

Reasoning

A shared authoritative record makes intended state recoverable, reviewable, and attributable. Without it, version-controlled definitions and operational practices can define conflicting system behaviour.

Application and service code, infrastructure, configuration, delivery pipelines, and database schemas all determine system state. Prototypes and scripts can also become deployed or depended upon, so treating them as short-lived work does not remove the need for an authoritative source.

Implemented By These Standards

Reproducible State

Summary

Systems and environments can be recreated consistently from their code-defined state without undocumented manual steps.

Reasoning

Recreating systems from code reduces environment-specific variance across development, test, and production. It also makes recovery independent of knowledge or state held only by an individual.

Undocumented post-creation steps leave part of the functional state outside the code definition and prevent consistent recreation.

Implemented By These Standards

Deterministic Generation

Summary

A generated artifact is reproducible from its authoritative source and generation process without manual modification.

Reasoning

Manual changes to generated output create state that its source and generation process cannot reproduce and that is lost when the output is generated again. Keeping changes in the source or generation process preserves the authoritative definition.

Stable output from unchanged inputs makes substantive changes distinguishable from incidental differences and allows independently generated results to be compared.

Implemented By These Standards

Code-Defined Change Path

Summary

Code-defined state changes through its reviewed and automated change path, with direct changes to running state subsequently incorporated into code.

Reasoning

Applying a change through the code-defined path preserves its review history, traceability, and repeatability. Manual or ad hoc actions create state outside those controls and allow running state to diverge from its authoritative definition.

Direct intervention can be necessary to restore service. Recording the resulting change in code keeps the definition authoritative and prevents the divergence from persisting.

Implemented By These Standards

Secrets Outside Code

Summary

Secrets remain in a dedicated secrets management system, and code-defined artifacts reference them without containing their values.

Reasoning

Embedding a secret in code exposes it through repository history, generated artifacts, and code review to people and systems that do not require it.

Referencing secrets at runtime allows credentials to be rotated independently of code and keeps their handling within the secrets management system.

Implemented By These Standards

Documentation Changes with Behaviour

Summary

Engineering documentation stays version-controlled and updated in the same change that alters the behaviour it describes.

Reasoning

Version control makes documentation changes reviewable and preserves their history alongside the source changes they describe.

Updating documentation with the behaviour change prevents it from describing an earlier system state and directing later work from incorrect information.