The Twelve-Factor App is a methodology for building cloud-native and SaaS applications, published by Adam Wiggins of Heroku at 12factor.net in 2011. Its factors include one codebase with many deploys, explicitly declared dependencies, config in environment variables, backing services as attached resources, strict build-release-run separation, stateless disposable processes, dev/prod parity and logs as event streams. The aim is portable, horizontally scalable services.

Twelve-Factor App

Details
Also known as

12-Factor App

Core Concepts:

Codebase

One codebase tracked in revision control, many deploys; a one-to-one relationship between app and codebase

Dependencies

Explicitly declare and isolate dependencies; never rely on implicit system-wide packages

Config in the environment

Store config (credentials, hostnames, per-deploy values) in environment variables, strictly separated from code

Backing services

Treat databases, queues, caches and SMTP as attached resources, swappable by changing config without code edits

Build, release, run

Strictly separate the three stages; releases are immutable and append-only, every release has a unique ID

Stateless, disposable processes

Execute the app as one or more stateless, share-nothing processes; persist state only in backing services. Maximize robustness with fast startup and graceful shutdown (Disposability)

Port binding

Export the service by binding to a port; the app is self-contained and needs no runtime webserver injection

Concurrency

Scale out horizontally via the process model, treating processes as first-class citizens

Dev/prod parity

Keep development, staging and production as similar as possible — small time, personnel and tooling gaps

Logs as event streams

Treat logs as time-ordered event streams written to stdout; the execution environment handles routing and storage

Admin processes

Run admin and management tasks (migrations, REPLs) as one-off processes in an identical environment to the long-running ones

Key Proponent

Adam Wiggins (Heroku, 12factor.net, 2011)

When to Use:

  • Designing or reviewing cloud-native and SaaS applications for portability and scalability

  • Establishing deployment, config and statelessness conventions for a containerized or PaaS workload

  • Onboarding developers to twelve-factor vocabulary (config-in-env, attached resources, build/release/run)

  • Prompting an LLM to scaffold a deployable, environment-portable service rather than a machine-bound one

Criticism:

  • Kevin Hoffman, "Beyond the Twelve-Factor App" (O’Reilly, 2016) — argues the original set is incomplete for modern cloud platforms and proposes a revised fifteen-factor methodology, adding API First, Telemetry and Authentication and Authorization as first-class factors

Current Status:

  • The canonical 12factor.net document was "Last updated 2017" and stood unchanged for roughly eight years; a training-data prior most plausibly serves this frozen 2011/2017 text

  • Salesforce/Heroku launched an official Twelve-Factor modernization initiative (Brian Hammons, 10 Feb 2025), an open-source effort revisiting the principles for containers, Kubernetes and serverless and proposing a new Identity factor