Website • Releases • Documentation

---

What is Ctrlplane?

Ctrlplane is the orchestration layer between your CI/CD pipelines and your infrastructure.

Your CI builds code. Your clusters run it. Ctrlplane decides when releases are ready, where they should deploy, and what gates they must pass—handling environment promotion, verification, approvals, and rollbacks automatically.

Your CI/CD    ──►    Ctrlplane    ──►    Your Infrastructure
 (builds)          (orchestrates)           (deploys)

Why Ctrlplane?

Problem	How Ctrlplane Helps
Manual environment promotion	Auto-promote staging → prod when verification passes
"Did the deploy actually work?"	Automated verification via Datadog, Prometheus, HTTP checks
Deploying to 50 clusters is painful	One deployment definition, Ctrlplane handles the fan-out
No visibility into what's running	Unified inventory: which version, which cluster, which region
Inconsistent deployment policies	Centralized policy engine with flexible selectors

🚀 Key Features

• Gradual Rollouts — Deploy to targets sequentially with configurable intervals and verification between each
• Policy Gates — Require approvals, enforce environment sequencing, set deployment windows
• Automated Verification — Integrate with Datadog, Prometheus, or any HTTP endpoint
• Auto-Rollback — Automatically revert when verification fails
• Infrastructure Inventory — Unified view of resources across Kubernetes, cloud providers, and custom infra
• Pluggable Execution — Works with ArgoCD, Kubernetes Jobs, GitHub Actions, Terraform Cloud, or custom agents

Who Is It For?

• Platform teams building internal developer platforms
• DevOps/SRE enforcing deployment policies at scale
• Engineering orgs with 10+ services across multiple environments
• Multi-region deployments needing coordinated rollouts

⚡ Quick Start

See our installation guide to get started.

Method	Link
Docker
Kubernetes

How It Works

1. CI creates a version — Your build pipeline registers a new version with Ctrlplane
2. Ctrlplane plans releases — Based on environments and selectors, it creates release targets
3. Policies are evaluated — Approval gates, environment progression, gradual rollout rules
4. Jobs execute — Ctrlplane dispatches to your job agent (ArgoCD, K8s Jobs, GitHub Actions)
5. Verification runs — Metrics are checked; pass → promote, fail → rollback

📚 Documentation

• Quickstart — Deploy your first service in 15 minutes
• Core Concepts — Systems, deployments, environments, resources
• Policies — Approvals, verification, gradual rollouts
• Integrations — GitHub Actions, ArgoCD, Kubernetes

🛠️ Contributing

We welcome contributions! This section covers everything you need to get the project running locally and start contributing.

Prerequisites

• Docker engine installed and running
• Flox installed (manages Node.js, pnpm, Go, and other tooling)
• pnpm (if not using Flox)
• Go 1.22+ (only needed if working on workspace-engine or relay)

First-Time Setup

git clone https://github.com/ctrlplanedev/ctrlplane.git
cd ctrlplane

# Activate the Flox environment (installs all required tooling)
flox activate

# Start local services (PostgreSQL, etc.)
docker compose -f docker-compose.dev.yaml up -d

# Install dependencies and build all packages
pnpm i && pnpm build

# Apply database migrations
pnpm -F @ctrlplane/db migrate

# Start all dev servers
pnpm dev

Reset everything (wipe volumes and start fresh):

docker compose -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.dev.yaml up -d
pnpm -F @ctrlplane/db migrate
pnpm dev

Day-to-Day Development

Command	Description
pnpm dev	Start all dev servers
pnpm build	Build all packages
pnpm test	Run all TypeScript tests
pnpm lint	Lint all TypeScript code
pnpm format:fix	Auto-format all TypeScript code
pnpm typecheck	TypeScript type check across all packages
pnpm -F <package> test	Run tests for a specific package
pnpm -F <package> test -- -t "test name"	Run a specific test by name

Database

pnpm -F @ctrlplane/db migrate   # Run migrations
pnpm -F @ctrlplane/db push      # Apply schema changes without a migration file (dev only)
pnpm -F @ctrlplane/db studio    # Open Drizzle Studio UI

E2E Tests (Playwright)

cd e2e
pnpm exec playwright test                                         # Run all e2e tests
pnpm exec playwright test tests/api/resources.spec.ts             # Run a specific file
pnpm test:api                                                     # Run all API tests
pnpm test:debug                                                   # Run in debug mode

workspace-engine (Go)

cd apps/workspace-engine
go run ./...                          # Run without building
go build -o ./bin/workspace-engine .  # Build binary
go test ./...                         # Run tests
golangci-lint run                     # Lint
go fmt ./...                          # Format

Monorepo Structure

apps/
  api/              # Node.js/Express REST API — core business logic
  web/              # React 19 + React Router frontend
  workspace-engine/ # Go reconciliation engine
  relay/            # Go WebSocket relay for agent communication
packages/
  db/               # Drizzle ORM schema + migrations (PostgreSQL)
  trpc/             # tRPC server setup
  auth/             # Authentication integration
integrations/       # External service adapters
e2e/                # Playwright end-to-end tests

Code Style

• TypeScript: explicit types, interface for public APIs, async/await, named imports
• React: functional components only, typed as const Foo: React.FC<Props> = () => {}
• Tests: vitest with typed fixtures
• Go: follow apps/workspace-engine/CLAUDE.md guidelines
• Run pnpm lint and pnpm format:fix before submitting a PR

Opening a Pull Request

1. Fork the repo and create a branch from main
2. Make your changes, add tests where applicable
3. Run pnpm test, pnpm lint, and pnpm typecheck to verify everything passes
4. Open a PR against main with a clear description of what changed and why

❤️ Community

• GitHub Discussions
• Discord

Ask questions, report bugs, join discussions, voice ideas, make feature requests, or share your projects.

⛓️ Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and not open a public issue.

Email security@ctrlplane.dev to disclose any security vulnerabilities.

---

We couldn't have done this without you