Nov 20, 20267 min read

The Twelve-Factor App in 2026: What Still Holds and What Changed

A practical review of the twelve factors for backends running on AWS, GCP and Kubernetes today, which ones every service should still follow, where secrets managers, containers and agents have changed the advice, and how to apply them without a pile of infrastructure scripts.

Illustration for The Twelve-Factor App in 2026: What Still Holds and What Changed

The twelve-factor app was written in 2011 for apps on a single PaaS, and much of it now describes how containers on ECS, Cloud Run or Kubernetes already behave. That makes it easy to nod along and still break it.

The usual breaks are config and secrets, the gap between laptop and production, and one-off scripts outside the deploy pipeline. This guide goes through all twelve factors, what still holds, and a service that follows them by default.

What Are the Twelve Factors?

The methodology lists twelve practices for software-as-a-service backends, and since it was open-sourced in 2024 it has been revised in the open. Here is each one, with how it applies today:

FactorThe ruleWhat it means in 2026
I. CodebaseOne codebase per app, many deploysOne repo per app or one app per monorepo folder, with every environment built from it
II. DependenciesDeclare and isolate dependenciesLockfiles and container images, never packages installed on the host
III. ConfigStore config in the environmentPlain settings in env, secrets in a secrets manager injected at runtime
IV. Backing servicesTreat them as attached resourcesDatabases, queues and buckets swapped per environment without code changes
V. Build, release, runStrictly separate stagesImmutable images, a release that pairs one image with config, rollbacks by release
VI. ProcessesStateless, share-nothing processesSessions, uploads and jobs in backing services, never on local disk
VII. Port bindingExport services via port bindingThe app serves HTTP itself, the platform routes to the port
VIII. ConcurrencyScale out via the process modelHorizontal scaling of separate web and worker processes
IX. DisposabilityFast startup, graceful shutdownHandle SIGTERM, drain requests, make jobs safe to retry
X. Dev/prod parityKeep environments similarThe same Postgres and queue semantics locally as in production
XI. LogsTreat logs as event streamsStructured lines on stdout, collected by the platform
XII. Admin processesRun admin tasks as one-off processesMigrations and scheduled tasks shipped with the app's release

Which Factors Do Teams Still Get Wrong?

Factors II, V, VII and VIII come almost for free with containers and a managed runtime. The ones that still cause incidents are the factors where the platform cannot enforce the rule for you.

Config (III). The original advice was to put all config, credentials included, in environment variables, which the config factor defines as anything that varies between deploys. Plain env vars are now considered a weak place for secrets, because they leak into crash dumps, child processes and env output in CI logs. Keep non-secret settings in env, put credentials in AWS Secrets Manager or Google Secret Manager, and inject them at runtime with access limited to the service that needs them.

Backing services (IV). The factor says a local Postgres and a managed one should be interchangeable through config. In practice, the attachment itself is where effort goes: each environment needs the database created, a user, network access and a connection string stored somewhere, and that is usually a Terraform module per resource type.

Dev/prod parity (X). The dev/prod parity factor names three gaps, time, personnel and tools, and the tools gap is the one that persists. A laptop running SQLite and an in-process queue behaves differently from RDS and SQS, so bugs in transactions, ordering and retries only appear after deploy.

Admin processes (XII). Migrations run by hand from a laptop, or cron jobs configured in a console with a different version of the code, break the rule that admin tasks ship with the release they belong to.

How Do Disposability and Concurrency Work on Containers?

Kubernetes, ECS and Cloud Run all stop containers with SIGTERM followed by SIGKILL after a grace period, so disposability now has a concrete meaning: stop accepting new work on SIGTERM, finish in-flight requests, and make background jobs idempotent so a job killed halfway can run again. Concurrency means separate process types, such as an API and a queue consumer, that scale independently, which on these platforms is separate services or deployments rather than one container running both.

Is Twelve-Factor Enough for AI-Assisted Development?

The factors were written for human teams, but they matter more when coding agents write a large share of the code. An agent working in a repo where config, infrastructure and admin scripts all live outside the code has to guess at them, while an agent working in a repo where backing services and schedules are declared in the code can see and change them in one diff. The config rule also gains a new reason: secrets that never enter the repo or a .env file cannot be read or leaked by the agent.

How Does Encore Apply the Twelve Factors?

Encore

Encore is a backend framework with built-in infrastructure, and several factors fall out of its design: backing services are declared in the code and attached per environment, secrets are injected at runtime from your cloud's secret manager, migrations and scheduled jobs ship with the release, and encore run starts the same kind of Postgres and Pub/Sub you use in production. The example is a small Go service that touches factors III, IV, X, XI and XII.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create invoices-api --example=hello-world$ cd invoices-api && mkdir -p invoices/migrations

The migration is the admin process for the schema, applied by Encore on every deploy and on encore run:

-- invoices/migrations/1_invoices.up.sql CREATE TABLE invoices ( id BIGSERIAL PRIMARY KEY, customer_id TEXT NOT NULL, amount_cents BIGINT NOT NULL, due_at TIMESTAMPTZ NOT NULL, reminded_at TIMESTAMPTZ ); CREATE INDEX invoices_due ON invoices (due_at) WHERE reminded_at IS NULL;

The service declares its database, a secret for the email provider and a cron job for reminders:

// invoices/invoices.go package invoices import ( "context" "encore.dev/cron" "encore.dev/rlog" "encore.dev/storage/sqldb" ) // Backing service: attached per environment, never a connection string in code. var db = sqldb.NewDatabase("invoices", sqldb.DatabaseConfig{ Migrations: "./migrations", }) // Config: the value is injected at runtime and never stored in the repo. var secrets struct { EmailAPIKey string } // Admin process: the schedule ships with the release that contains the code. var _ = cron.NewJob("invoice-reminders", cron.JobConfig{ Title: "Send reminders for overdue invoices", Schedule: "0 8 * * *", Endpoint: SendReminders, }) type ReminderResult struct { Sent int `json:"sent"` } //encore:api private func SendReminders(ctx context.Context) (*ReminderResult, error) { rows, err := db.Query(ctx, ` UPDATE invoices SET reminded_at = now() WHERE id IN ( SELECT id FROM invoices WHERE due_at < now() AND reminded_at IS NULL ORDER BY due_at LIMIT 100 FOR UPDATE SKIP LOCKED ) RETURNING id, customer_id`) if err != nil { return nil, err } defer rows.Close() sent := 0 for rows.Next() { var id int64 var customerID string if err := rows.Scan(&id, &customerID); err != nil { return nil, err } if err := sendReminder(ctx, customerID, id); err != nil { rlog.Error("reminder failed", "invoice_id", id, "err", err) continue } sent++ } // Logs: structured fields on stdout, collected by the platform. rlog.Info("reminders sent", "count", sent) return &ReminderResult{Sent: sent}, rows.Err() } func sendReminder(ctx context.Context, customerID string, invoiceID int64) error { _ = secrets.EmailAPIKey // Call the email provider with this key. return nil }

encore run starts Postgres, applies the migration and serves the endpoint, so dev/prod parity covers the database itself rather than a stand-in. Cron jobs do not run locally, so call SendReminders from the local dashboard or a test while developing; in deployed environments the schedule is Encore platform managed, with no extra infrastructure in your account. On deploy to your AWS or GCP account, the database becomes RDS or Cloud SQL and the secret is read from your cloud's secret manager at runtime. The reminder query claims rows with SKIP LOCKED and marks them in the same statement, so a retried or overlapping run does not remind the same invoice twice.

An agent asked to add late fees writes a second migration, the query and, if needed, a new job in one change, and runs the service locally against that Postgres, without a separate infrastructure repo to update.

Best fit: teams starting a new backend who want it to follow the twelve factors from the first commit, running in their own AWS or GCP account.

Twelve-Factor Checklist

  • Build every environment from one codebase and one immutable image per release.
  • Keep non-secret config in env and secrets in a secrets manager.
  • Attach databases, queues and buckets per environment without code changes.
  • Keep processes stateless and handle SIGTERM with a graceful drain.
  • Run the same Postgres and queue semantics locally as in production.
  • Write structured logs to stdout.
  • Ship migrations and scheduled jobs with the release that needs them.

Frequently asked questions

What is a twelve-factor app?

A twelve-factor app follows a methodology for building software-as-a-service backends that are portable, scale out by adding processes and deploy continuously. The twelve factors cover one codebase per app, declared dependencies, config outside the code, backing services as attached resources, separate build and run stages, stateless processes, port binding, concurrency, disposability, dev/prod parity, logs as event streams and one-off admin processes.

Is the twelve-factor app still relevant in 2026?

Yes. Most factors describe how containers on Kubernetes, ECS or Cloud Run already expect apps to behave, such as stateless processes, fast startup, graceful shutdown and logs on stdout. The factor on config is the one usually applied differently today, keeping secrets in a secrets manager rather than in plain environment variables.

What is dev/prod parity in twelve-factor?

Dev/prod parity means keeping development and production as similar as possible: the same backing services such as Postgres rather than SQLite, deploys within hours of writing code, and the same people writing and deploying it. Tools that run the same database and queue locally make the backing service gap the easiest one to close.

Who created the twelve-factor app methodology?

It was written in 2011 by Adam Wiggins and other engineers at Heroku, based on what they saw across many apps on the platform. In November 2024 the methodology was open-sourced so the community could update it for modern cloud platforms.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders