Skip to content
Skills Library
DevOps & cloud · Learning & explanation

12-factor-app

/12-factor-app

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Repository
dot-skills ↗
Licence
MIT
Last repository change
15.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
56
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Original author description

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

How it works

  1. When to Apply
  2. Rule Categories by Priority
  3. Quick Reference
  4. How to Use
  5. Reference Files
Original SKILL.md headings · 137 lines, 914 words
SKILL.md preview
---
name: 12-factor-app
description: The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.
---

# Community Cloud-Native Applications Best Practices

Comprehensive methodology for building modern software-as-a-service applications that are portable, scalable, and maintainable. Contains 51 rules across 12 categories, covering the entire application lifecycle from codebase management to production operations.

## When to Apply

Reference these guidelines when:
- Designing new backend services or APIs
- Containerizing applications for Kubernetes or Docker
- Setting up CI/CD pipelines
- Managing configuration across environments
- Implementing logging and monitoring
- Planning application scaling strategy
- Debugging deployment or environment issues

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Codebase & Version Control | CRITICAL | `code-` |
| 2 | Dependencies | CRITICAL | `dep-` |
| 3 | Configuration | CRITICAL | `config-` |
| 4 | Backing Services | HIGH | `svc-` |
| 5 | Build, Release, Run | HIGH | `build-` |
| 6 | Processes & State | HIGH | `proc-` |
| 7 | Concurrency & Scaling | HIGH | `scale-` |
| 8 | Disposability | HIGH | `disp-` |
| 9 | Port Binding | MEDIUM | `port-` |
| 10 | Dev/Prod Parity | MEDIUM | `parity-` |
| 11 | Logging | MEDIUM | `log-` |
| 12 | Admin Processes | MEDIUM | `admin-` |

## Quick Reference

### 1. Codebase & Version Control (CRITICAL)

- [`code-single-codebase`](references/code-single-codebase.md) - Maintain one codebase per application in version control
- [`code-one-app-one-repo`](references/code-one-app-one-repo.md) - Enforce one-to-one correlation between codebase and application
- [`code-deploys-not-branches`](references/code-deploys-not-branches.md) - Use deploys not branches to represent environments
- [`code-shared-as-libraries`](references/code-shared-as-libraries.md) - Factor shared code into libraries managed by dependency manager

### 2. Dependencies (CRITICAL)

- [`dep-explicit-declaration`](references/dep-explicit-declaration.md) - Declare all dependencies explicitly in a manifest file
- [`dep-isolate-execution`](references/dep-isolate-execution.md) - Isolate dependencies to prevent system package leakage
- [`dep-no-system-tools`](references/dep-no-system-tools.md) - Never rely on implicit system tools being available
- [`dep-deterministic-builds`](references/dep-deterministic-builds.md) - Use lockfiles for deterministic dependency resolution

### 3. Configuration (CRITICAL)

- [`config-separate-from-code`](references/config-separate-from-code.md) - Strictly separate configuration from code
- [`config-use-env-vars`](references/config-use-env-vars.md) - Store configuration in environment variables
- [`config-no-env-groups`](references/config-no-env-groups.md) - Treat environment variables as granular controls not grouped environments
- [`config-validate-on-startup`](references/config-validate-on-startup.md) - Validate required configuration at application startup
- [`config-never-commit-secrets`](references/config-never-commit-secrets.md) - Never commit secrets or credentials to version control

### 4. Backing Services (HIGH)

- [`svc-as-attached-resources`](references/svc-as-attached-resources.md) - Treat backing services as attached resources
- [`svc-connection-strings`](references/svc-connection-strings.md) - Reference all backing services via connection URLs in config
- [`svc-no-local-vs-remote`](references/svc-no-local-vs-remote.md) - Make no distinction between local and third-party services
- [`svc-detach-attach-without-code`](references/svc-detach-attach-without-code.md) - Design services to be detachable and attachable without code changes

### 5. Build, Release, Run (HIGH)

- [`build-separate-stages`](references/build-separate-stages.md) - Strictly separate build, release, and run stages
- [`build-immutable-releases`](references/build-immutable-releases.md) - Create immutable releases with unique identifiers
- [`build-no-runtime-changes`](references/build-no-runtime-changes.md) - Never modify code at runtime - changes require new release
- [`build-complexity-in-build`](references/build-complexity-in-build.md) - Push complexity into build stage keep run stage minimal
- [`build-artifact-per-commit`](references/build-artifact-per-commit.md) - Generate one build artifact per commit deploy same artifact everywhere

### 6. Processes & State (HIGH)

- [`proc-stateless-processes`](references/proc-stateless-processes.md) - Execute the application as stateless processes
- [`proc-no-sticky-sessions`](references/proc-no-sticky-sessions.md) - Never use sticky sessions - store session data in backing services
- [`proc-no-local-filesystem`](references/proc-no-local-filesystem.md) - Never assume local filesystem persists between requests
- [`proc-compile-at-build`](references/proc-compile-at-build.md) - Perform asset compilation and bundling at build time not runtime
- [`proc-share-nothing`](references/proc-share-nothing.md) - Design processes to share nothing with each other

### 7. Concurrency & Scaling (HIGH)

- [`scale-process-model`](references/scale-process-model.md) - Scale out via the process model with multiple process types
- [`scale-process-types`](references/scale-process-types.md) - Assign workloads to appropriate process types
- [`scale-no-daemonize`](references/scale-no-daemonize.md) - Never daemonize or write PID files let process manager handle it
- [`scale-horizontal-not-vertical`](references/scale-horizontal-not-vertical.md) - Design for horizontal scaling over vertical scaling
- [`scale-process-formation`](references/scale-process-formation.md) - Define process formation as declarative configuration

### 8. Disposability (HIGH)

- [`disp-disposable-processes`](references/disp-disposable-processes.md) - Design processes to be disposable started or stopped at any moment
- [`disp-fast-startup`](references/disp-fast-startup.md) - Minimize startup time to enable rapid scaling and recovery
- [`disp-graceful-shutdown`](references/disp-graceful-shutdown.md) - Implement graceful shutdown on SIGTERM
- [`disp-crash-only`](references/disp-crash-only.md) - Design for crash-only software that recovers from sudden death
- [`disp-idempotent-operations`](references/disp-idempotent-operations.md) - Make operations idempotent to safely retry after failures

### 9. Port Binding (MEDIUM)

- [`port-self-contained`](references/port-self-contained.md) - Make the application completely self-contained with embedded server
- [`port-export-via-binding`](references/port-export-via-binding.md) - Export services via port binding using PORT environment variable
- [`port-any-protocol`](references/port-any-protocol.md) - Use port binding to export any protocol not just HTTP

### 10. Dev/Prod Parity (MEDIUM)

- [`parity-minimize-gaps`](references/parity-minimize-gaps.md) - Minimize gaps between development and production environments
- [`parity-same-backing-services`](references/parity-same-backing-services.md) - Use the same type and version of backing services in all environments
- [`parity-deploy-frequently`](references/parity-deploy-frequently.md) - Deploy frequently to minimize the time gap
- [`parity-developers-deploy`](references/parity-developers-deploy.md) - Involve developers in deployment to minimize personnel gap

### 11. Logging (MEDIUM)

- [`log-event-streams`](references/log-event-streams.md) - Treat logs as event streams not files
- [`log-no-routing`](references/log-no-routing.md) - Never route or store logs from within the application
- [`log-structured-format`](references/log-structured-format.md) - Use structured logging for machine-readable event streams
- [`log-unbuffered-stdout`](references/log-unbuffered-stdout.md) - Write logs unbuffered to stdout for real-time streaming

### 12. Admin Processes (MEDIUM)

- [`admin-one-off-processes`](references/admin-one-off-processes.md) - Run admin tasks as one-off processes not special scripts
- [`admin-same-environment`](references/admin-same-environment.md) - Run admin processes against a release with same codebase and config
- [`admin-repl-access`](references/admin-repl-access.md) - Provide REPL access for debugging and data inspection

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |
Files in this package (56)
  • AGENTS.md 12 KB
  • SKILL.md 9 KB
  • metadata.json 1 KB
  • assets/templates/_template.md 1 KB
  • references/_sections.md 2 KB
  • references/admin-one-off-processes.md 3 KB
  • references/admin-repl-access.md 3 KB
  • references/admin-same-environment.md 3 KB
  • references/build-artifact-per-commit.md 3 KB
  • references/build-complexity-in-build.md 2 KB
  • references/build-immutable-releases.md 2 KB
  • references/build-no-runtime-changes.md 2 KB
  • references/build-separate-stages.md 2 KB
  • references/code-deploys-not-branches.md 2 KB
  • references/code-one-app-one-repo.md 2 KB
  • references/code-shared-as-libraries.md 2 KB
  • references/code-single-codebase.md 2 KB
  • references/config-never-commit-secrets.md 2 KB
  • references/config-no-env-groups.md 2 KB
  • references/config-separate-from-code.md 2 KB
  • references/config-use-env-vars.md 2 KB
  • references/config-validate-on-startup.md 2 KB
  • references/dep-deterministic-builds.md 2 KB
  • references/dep-explicit-declaration.md 2 KB
  • references/dep-isolate-execution.md 2 KB
  • references/dep-no-system-tools.md 2 KB
  • references/disp-crash-only.md 3 KB
  • references/disp-disposable-processes.md 3 KB
  • references/disp-fast-startup.md 3 KB
  • references/disp-graceful-shutdown.md 3 KB
  • references/disp-idempotent-operations.md 3 KB
  • references/log-event-streams.md 3 KB
  • references/log-no-routing.md 3 KB
  • references/log-structured-format.md 3 KB
  • references/log-unbuffered-stdout.md 3 KB
  • references/parity-deploy-frequently.md 3 KB
  • references/parity-developers-deploy.md 3 KB
  • references/parity-minimize-gaps.md 3 KB
  • references/parity-same-backing-services.md 3 KB
  • references/port-any-protocol.md 4 KB
  • references/port-export-via-binding.md 2 KB
  • references/port-self-contained.md 2 KB
  • references/proc-compile-at-build.md 3 KB
  • references/proc-no-local-filesystem.md 3 KB
  • references/proc-no-sticky-sessions.md 3 KB
  • references/proc-share-nothing.md 3 KB
  • references/proc-stateless-processes.md 2 KB
  • references/scale-horizontal-not-vertical.md 3 KB
  • references/scale-no-daemonize.md 3 KB
  • references/scale-process-formation.md 3 KB
  • references/scale-process-model.md 3 KB
  • references/scale-process-types.md 4 KB
  • references/svc-as-attached-resources.md 2 KB
  • references/svc-connection-strings.md 2 KB
  • references/svc-detach-attach-without-code.md 2 KB
  • references/svc-no-local-vs-remote.md 3 KB

Versions

The database has no other skills named 12-factor-app.

Database snapshot: 13.11.2026 · package version 54a7b778fa46 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100twelve-factor
    Guide for 12-Factor cloud-native applications. Use when designing microservices, configuring containers, deploying to Kubernetes, or following cloud-native patterns.
  • 100twelve-factor
    Expert Twelve-Factor App methodology assistance covering declarative setup, environment configuration, backing service bindings, stateless processes, and concurrency models. Use when architecting cloud-native applications, containerizing web services, or standardizing 12-factor compliance.
  • 9512-factor-apps
    Perform 12-Factor App compliance analysis on any codebase. Use when evaluating application architecture, auditing SaaS applications, or reviewing cloud-native applications against the original 12-Factor methodology.
  • 9512-factor-apps
    Perform 12-Factor App compliance analysis on any codebase. Use when evaluating application architecture, auditing SaaS applications, or reviewing cloud-native applications against the original 12-Factor methodology.
  • 100twelve-factor
    Use when designing, deploying, or evaluating cloud-native applications — based on the Twelve-Factor App methodology from Heroku. USE FOR: cloud-native app design, environment configuration, stateless process design, backing service integration, build/release/run pipelines,…
  • 95twelve-factor
    Twelve-Factor App methodology for building deployable software-as-a-service applications. Use when configuring environment variables, connecting to backing services, structuring startup/shutdown, handling process signals, setting up CI/CD pipelines, or auditing deployment…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.