twelve-factor-app-principles

Twelve-Factor App Principles

The Twelve-Factor App (12factor.net) is a methodology for building services that can be deployed, scaled, and handed off between engineers without hidden local state or environment-specific assumptions. This skill paraphrases its own principles — for the canonical text, see the source website rather than copying prose from here.

Rather than restate all twelve one by one, group them by the failure mode each one prevents — this is more useful for review than memorizing a list.

Group 1: One codebase, config and environment kept out of code

• One codebase tracked in version control, many deploys from it. Every running instance — local, staging, production — traces back to the same repository at different points in its history; if two environments are running code that lives in genuinely different repositories (a fork, a copy-pasted variant), you no longer have one deployable app, you have two apps pretending to be one. A service should never require its own divergent copy of the repo per environment.
• Config in the environment, not in code. Anything that varies between deploys (database URLs, API keys, feature flags, hostnames) belongs in environment variables or a secrets manager, never hardcoded or committed in a config file checked into version control. A quick test: could you make the repository public without leaking a secret or an environment-specific value? If not, something in "config" is misplaced.
• Dev/prod parity. Keep the gap between local, staging, and production as small as possible — same backing service types (don't run SQLite locally and Postgres in prod), same dependency versions, short lead time between a code change and its deploy. Most "works on my machine" bugs trace back to a parity gap here.

Group 2: Backing services are attached resources, not internal state

• Every external system a service talks to — its database, a queue, a cache, a third-party API — should be swappable purely by changing a config value, with no code change required. A service shouldn't need a code change to point at a different Postgres instance — only a changed connection string. This makes it easy to point a local dev environment at a throwaway instance without touching the code that talks to it.
• Explicit, declared dependencies. Every library the service needs is declared in a manifest (go.mod, package.json) and pinned — never relying on something happening to be present on the host system.