12 foundations + 10 modern extensions

The 22-Factor App

An independent ORESoftware extension of the Twelve-Factor methodology for secure, portable, recoverable, and human-accountable cloud systems.

Read the modern ten Browse all 22 Primary references

An extension, not an official replacement

The first twelve factors remain recognizable and are paraphrased for continuity. Factors XIII–XXII are an ORESoftware proposal. The original project and the active community modernization effort are linked below.

Factors I–XII

The application foundations

One codebase, explicit dependencies, deploy-varying configuration, attached resources, immutable releases, stateless processes, and disciplined operations.

Foundation

Codebase

One authoritative codebase; every deploy is a version of it.

Keep application source and the declarations needed to reproduce it in one revision-controlled lineage. Environments are deploys of that lineage, not copied repositories that quietly diverge.

Operational contract

Trace every running instance to a commit and immutable release identifier.
Keep migrations, configuration schemas, and deployment declarations beside the code they govern.
Treat forks as contributions and experiments, not separate production codebases.

Foundation

Dependencies

Declare, lock, verify, and isolate every dependency.

An app must not depend on undeclared software that happens to exist on a laptop or host image. Manifests and lock data make builds repeatable; isolation prevents ambient packages from changing behavior.

Operational contract

Commit dependency manifests and deterministic lock data.
Verify provenance, checksums, licenses, and known vulnerabilities before release.
Run through the declared toolchain rather than globally installed packages.

Foundation

Configuration

Separate deploy-varying configuration from application code.

Code should be identical across deploys. Track configuration names, types, defaults, and validation rules while supplying environment-specific values through explicit release or runtime interfaces.

Operational contract

Fail fast when required configuration is missing or malformed.
Do not hide deployment policy in source constants or environment-name branches.
Keep settings orthogonal so one value can change without rebuilding unrelated configuration.

Foundation

Backing Services

Treat databases, queues, caches, and APIs as attached resources.

Reach backing services through configuration and stable contracts. A managed service, self-hosted service, or test double should be replaceable without changing core application code.

Operational contract

Put addresses and credentials behind typed configuration.
Define timeouts, retry budgets, health checks, and failure behavior for every dependency.
Exercise replacement, failover, backup, and restore paths before they are needed.

Foundation

Build, Release, Run

Build once, release deliberately, and run the exact artifact.

Compilation and packaging produce an immutable artifact. A release binds that artifact to reviewed configuration and migration intent. Runtime starts the already-created release and never edits it in place.

Operational contract

Promote the same artifact digest through environments instead of rebuilding it.
Give every release an immutable identity covering code, artifact, configuration, and schema intent.
Make migrations explicit, observable, and recoverable release steps.

Foundation

Processes

Run as stateless, share-nothing processes.

Processes may be created, moved, or destroyed at any time. Durable data belongs in backing services; memory and local files are caches or temporary workspace, never the only copy of important state.

Operational contract

Make handlers idempotent where retries or duplicate delivery are possible.
Do not depend on sticky sessions for correctness.
Keep local filesystem writes disposable, bounded, and safe to lose.

Foundation

Port Binding

Expose services through explicit ports and protocols.

The app publishes its network interface directly. The platform routes traffic to that interface instead of requiring an implicit application server or machine-specific integration.

Operational contract

Bind to an explicit, configurable, unprivileged port.
Publish protocol, health, readiness, and shutdown contracts.
Keep routing, TLS termination, and discovery in the platform boundary.

Foundation

Concurrency

Scale independent process types independently.

Model web serving, background work, scheduling, streaming, and administration as explicit process types. Scale horizontally and coordinate work through queues, partitions, or leases.

Operational contract

Give each process type independent limits and autoscaling signals.
Use backpressure and bounded queues so load cannot become unbounded memory growth.
Protect singleton duties with leases or fencing.

Foundation

Disposability

Start quickly, stop gracefully, and survive interruption.

Processes should become ready promptly and handle termination as an ordinary event. Work remains correct across crashes, rolling replacements, preemption, and duplicate delivery.

Operational contract

Stop taking new work and finish or safely abandon in-flight work within a deadline.
Use acknowledgements, leases, and idempotency so interrupted work can resume.
Test abrupt termination as well as graceful shutdown.

Foundation

Environment Parity

Keep development, test, staging, and production materially alike.

Reduce differences in people, time, tooling, service versions, and artifact shape. Local substitutes are useful only when compatibility is continuously checked against production contracts.

Operational contract

Use the same locked dependencies, migrations, and release artifact everywhere.
Keep deployment automation available to developers and exercise it frequently.
Run contract and end-to-end tests against production-equivalent backing services.

Foundation

Logs

Emit structured event streams; let the platform route and retain them.

Write machine-parseable events to standard output or another explicit telemetry interface. The application does not manage log files, retention, or destination-specific transports.

Operational contract

Include severity, service identity, release identity, and trace or correlation IDs.
Never emit secrets, decrypted configuration, session tokens, or unnecessary personal data.
Keep routing, indexing, retention, and alerting outside the process.

Foundation

Admin Tasks

Run maintenance work as auditable one-off processes.

Migrations, repairs, imports, and diagnostics run from the same code and dependency set as the release they affect, with the same identity and configuration boundaries.

Operational contract

Version admin commands with the application and make them safe to retry.
Record operator, inputs, release, start, completion, and outcome.
Use locks, leases, or fencing for operations that must not overlap.

Factors XIII–XXII

The modern security and delivery layer

The additional ten address encrypted configuration, minimal trust roots, software supply chains, multi-tenant isolation, immutable fleets, long-lived connections, autonomous tooling, human authority, review quality, and shared Git history.

Encrypted configBootstrap trustOCI portability IsolationImmutable hostsConnection recovery Tagged releasesHuman authorityCode review Shared history

Reference profile for XIII + XIV

Ciphertext is durable. Plaintext is disposable.

Track approved SOPS-encrypted dotenv values under env/enc/. Decrypt only on an authorized workstation or workload into ignored, owner-only env/dec/*.env files, memory, or tmpfs. Fiducia Cloud supplies no more than one or two external bootstrap secrets; it does not duplicate the application configuration.

env/enc/ is tracked and exact-path allowlisted.
env/dec/ is ignored, local-only, and safe to delete.
Decryption identities never enter Git, image layers, logs, caches, or artifacts.
The active root .env, when needed, is a managed link into env/dec/.

env/
├── enc/
│   ├── dev.env.enc
│   └── prod.env.enc
└── dec/              # ignored
    ├── dev.env
    └── prod.env

.env → env/dec/dev.env

Decrypt atomically • validate before install • permissions 0700/0600 • clean on exit

Modern extension

Secure the path from commit to operation

Each extension has an observable acceptance boundary that can be proven from repository policy, release evidence, runtime configuration, and audit logs.

Modern extension

Encrypted Configuration

Commit ciphertext; materialize plaintext only at the point of use.

Extend Factor III by tracking approved SOPS-encrypted dotenv files under env/enc/ while keeping plaintext local and disposable. Decrypt atomically into ignored env/dec/*.env files, memory, or tmpfs—never image layers, logs, caches, or artifacts.

Operational contract

Allowlist exact paths such as env/enc/dev.env.enc and env/enc/prod.env.enc.
Ignore env/dec/ completely; create owner-only files and replace them atomically after validation.
Keep decryption identities outside the repository and separate development, production, and recovery recipients.
Use keyless CI checks to reject tracked plaintext, broad encryption rules, symlink escapes, and malformed ciphertext.
Rotate application credentials after access removal or compromise because old Git objects remain history.

Modern extension

Bootstrap Secrets

Keep the off-repository trust root deliberately tiny.

Use Fiducia Cloud for only one or two secrets that cannot safely be represented as repository ciphertext—typically a bootstrap credential, root-key reference, or emergency recovery capability. Prefer workload identity and short-lived leases.

Operational contract

Do not mirror the entire application configuration in both Fiducia Cloud and env/enc/.
Scope reads to one workload, one environment, and the minimum secret names required.
Audit every read and rotation; expire bootstrap material quickly and fail closed.
Avoid circular bootstrap that requires another long-lived secret to fetch the first.
Keep break-glass access separately controlled, time-bounded, and reviewed after use.

Modern extension

OCI Artifacts

Package to OCI standards, not to a Docker dependency.

The production contract is an Open Container Initiative image, runtime bundle, and distribution interface. The Docker daemon, Docker CLI, Dockerfile, and Docker Hub are not required build, release, registry, or runtime dependencies.

Operational contract

Build with an OCI-native daemonless toolchain and run with an OCI-conformant runtime.
Pin deployments to content digests, never mutable image names alone.
Generate an SBOM and attach signed provenance and policy attestations.
Use minimal, non-root, read-only images with explicit capabilities and limits.
Promote the same verified digest through environments.

Modern extension

Isolation Boundaries

Match the isolation boundary to the workload’s risk.

A standard OCI process container is not the only choice. Trusted single-tenant code may use namespaces and cgroups; untrusted or multi-tenant code may require a userspace kernel, lightweight VM, microVM, virtual OS, or full VM.

Operational contract

Document the threat model, tenant boundary, kernel exposure, and performance budget.
Use gVisor, Kata Containers, Firecracker, or a full VM when risk warrants stronger isolation.
Avoid privileged containers and host namespace sharing; grant capabilities individually.
Test escape resistance, syscall compatibility, and degraded-mode behavior.
Make isolation level an explicit deployment property.

Modern extension

Immutable Infrastructure

Replace infrastructure; do not repair it in place.

Hosts, nodes, and base images are versioned artifacts. Build and test an AMI on AWS—or the equivalent machine image elsewhere—then create replacement capacity instead of patching long-lived machines through SSH.

Operational contract

Build, scan, test, and sign machine images in an automated pipeline.
Prohibit untracked in-place mutation and treat drift as a replacement signal.
Keep durable state in managed backing services or explicitly replicated volumes.
Promote the same image identifier and retain known-good rollback images.
Rehearse node replacement, rebalancing, and disaster recovery.

Modern extension

Recoverable Connections

Treat every TCP or WebSocket connection as interruptible, drainable, and resumable.

Long-lived connections are temporary transport, not durable state. During rollout or failure, servers stop accepting new sessions, advertise unready status, drain within a deadline, complete the close handshake, and let clients reconnect without corrupting work.

Operational contract

Use heartbeats, idle deadlines, bounded buffers, backpressure, and per-connection limits.
Reconnect with randomized exponential backoff and a retry budget to avoid a recovery stampede.
Use resumable cursors or session tokens, message IDs, idempotency keys, and duplicate suppression.
Keep session state in a backing service; affinity may help locality but must not be required.
For stateful stores, define and test quorum, fencing, backup, restore, and failover ownership.

Modern extension

Tag-Based Releases

Branches are proposals; protected Git tags are releases.

Branches can build and test, but production deployment begins only from a protected, annotated or signed release tag pointing to a reviewed commit. The tag resolves to immutable artifact digests, machine images, migration intent, and evidence.

Operational contract

Use a documented tag namespace such as vX.Y.Z or site-vX.Y.Z.
Restrict tag creation, updates, and deletion and record approval evidence.
Promote already-built artifacts instead of rebuilding per environment.
Reject deployment from mutable branch heads or mutable image tags.
Rollback by selecting a prior release tag and its original artifacts.

Modern extension

Human Authority

Automate evidence; keep accountable humans in control of consequential decisions.

Automation prepares diffs, tests, risk analysis, rollout plans, and recommendations. Humans retain explicit authority for production, security, privacy, financial, destructive, and otherwise irreversible actions according to a documented risk tier.

Operational contract

Show reviewers the exact change, evidence, blast radius, observability, and rollback plan.
Require an independent approver and two-person control for high-risk releases and destructive operations.
Do not let an agent, bot, or change author satisfy its own approval.
Pre-authorize low-risk reversible classes only through a reviewed narrow policy.
Make emergency access time-limited, fully audited, and retrospectively reviewed.

Modern extension

Code Review

Ship small, evidence-backed changes reviewed by the right owners.

A pull request should express one coherent change and make intent, risk, tests, migration behavior, operational effects, and rollback strategy understandable. Automated and AI review supplement independent human review; they do not replace ownership.

Operational contract

Keep changes focused and separate unrelated refactors from behavior changes.
Request code-owner, domain, security, or data review according to risk.
Review design, correctness, failure modes, tests, observability, migrations, and documentation.
Resolve substantive discussions and make generated or binary changes inspectable.
Respond promptly, distinguish blocking findings from optional polish, and record decisions.

Modern extension

History Integration

Rebase private work; merge shared history.

Rebase or squash unpublished local commits when that clarifies a private branch. Once work is shared, reviewed, protected, or released, preserve its identity and integrate it through the repository’s documented merge policy.

Operational contract

Never rewrite protected branches, public release tags, or commits collaborators may use.
Prefer a merge commit when topology, attribution, and semantic integration matter.
Allow squash merges for truly atomic routine changes when repository policy permits.
Resolve conflicts conceptually, never by choosing ours or theirs blindly, then rerun checks.
Place release tags on the final integrated commit, not a pre-merge branch tip.

Primary references

Standards and guidance behind the extension

These sources inform the operating contracts. The ten-factor extension and its wording are ORESoftware work; linked projects retain their names and licenses.

The Twelve-Factor App The original twelve factors and their historical context. Open reference Twelve-Factor modernization repository The community-led work updating the original manifesto. Open reference ORESoftware SOPS environment-file standard The exact env/enc and env/dec operating profile used here. Open reference Fiducia Cloud The narrow external-secret and distributed trust service in Factor XIV. Open reference SOPS documentation Encrypted dotenv and structured configuration with identity-based key access. Open reference Open Container Initiative Open image, runtime, and distribution specifications. Open reference gVisor A userspace application kernel and OCI runtime for sandboxed containers. Open reference Kata Containers OCI-compatible containers backed by lightweight virtual machines. Open reference Firecracker A minimal KVM-based microVM monitor for multi-tenant workloads. Open reference AWS EC2 Image Builder Automated, tested machine-image and AMI pipelines. Open reference Kubernetes Pod lifecycle Termination, readiness, and connection-draining behavior. Open reference RFC 6455: The WebSocket Protocol Closing handshakes, ping/pong, and reconnect backoff. Open reference GitHub repository rulesets Controls for branches, tags, required reviews, and protected history. Open reference Google Engineering Practices: Code Review Small changes, reviewer responsibilities, and review quality. Open reference Git: The Perils of Rebasing Why published shared commits should not be rewritten. Open reference

Adoption rule

Prefer proof over slogans.

A factor is adopted when its contract is encoded in source, policy, tests, release evidence, runtime controls, and recovery drills—not merely mentioned in a README.

Improve this proposal