Twelve-Factor App Compliance Checklist

When to Use This Checklist

Use this checklist to assess whether an application follows the twelve-factor methodology, a set of principles for building software that runs cleanly on modern cloud platforms. The twelve factors describe how to handle configuration, dependencies, state, and processes so an app is portable, scalable, and easy to operate. Run this audit before a cloud migration or as a periodic health check.

How to Use This Checklist

Work through each factor and rate the app as compliant, partial, or non-compliant. The factors most often violated by legacy apps are configuration (values hardcoded instead of read from the environment), stateless processes (local session or file state), and logs (written to files instead of stdout). Treat configuration, statelessness, and dev/prod parity as priority fixes because they block containerization and horizontal scaling.

Use the audit output to build a remediation backlog ordered by impact.

What Good Looks Like

A twelve-factor-compliant app keeps one codebase per app in version control, declares dependencies explicitly, and reads all configuration from the environment. Processes are stateless and disposable with fast startup and graceful shutdown. Build, release, and run are separate stages; environments are near-identical; and logs stream to stdout for the platform to aggregate.

Common Pitfalls

The most common violations are configuration baked into code or images, and processes that hold local state and so cannot scale horizontally. Teams also write logs to files, which breaks in ephemeral containers. Large gaps between dev and production environments cause "works on my machine" failures. Slow or unclean shutdown breaks rolling deployments.

Related Resources

See the twelve-factor app methodology and CNCF cloud-native principles. Configuration as code and secrets management cover factor three, immutable infrastructure supports the build/release/run split, and structured logging supports treating logs as event streams.