Skip to main content
Ctrlplane’s deployment system orchestrates releases across environments with configurable policies, verification, and approval workflows.

​
What is Deployment Orchestration?

Deployment orchestration manages how releases flow through your environments — from build to production — with:
  • Gradual rollouts — Deploy to targets sequentially with verification between each
  • Policy-driven gates — Approvals, verification, and dependencies
  • Environment promotion — Automated staging → production progression
  • Rollback & recovery — Automatic rollback on verification failure

​
Core Concepts

Systems

Logical groupings of related deployments

Deployments

Services or applications to deploy

Releases & Jobs

Deployment execution units

Release Targets

Deployment × Environment × Resource

​
How It Works

​
1. CI Creates Versions

Your CI pipeline creates a version after successful builds: 
- name: Create Version
  env:
    CTRLPLANE_API_KEY: ${{ secrets.CTRLPLANE_API_KEY }}
  run: |
    ctrlc api upsert version \
      --workspace ${{ vars.CTRLPLANE_WORKSPACE }} \
      --deployment ${{ vars.CTRLPLANE_DEPLOYMENT_ID }} \
      --tag ${{ github.sha }} \
      --name "Build #${{ github.run_number }}" \
      --metadata git/commit=${{ github.sha }} \
      --metadata git/branch=${{ github.ref_name }}

​
2. Ctrlplane Creates Releases

For each release target (deployment × environment × resource), Ctrlplane:
  1. Evaluates policies (approvals, gates, dependencies)
  2. Creates a release with the new version
  3. Dispatches a job to the job agent

​
3. Job Agents Execute

Job agents perform the actual deployment:
  • GitHub Actions — Trigger workflows
  • ArgoCD — Create/sync Applications
  • Terraform Cloud — Create workspaces and runs

​
4. Verification Validates

After deployment, verification checks health metrics (error rates, latency, etc.) and automatically determines whether the release should proceed or roll back. See Verification for details.

​
Defining a Deployment

A deployment connects what (your service) with how (the job agent that executes it). You can define deployments via Terraform, CLI, or API. 
resource "ctrlplane_deployment" "api" {
  name              = "API Service"
  resource_selector = "resource.kind == 'Kubernetes' && resource.metadata['status'] == 'running'"

  metadata = {
    team    = "backend"
    service = "api"
  }

  job_agent {
    id = ctrlplane_job_agent.github.id

    github {
      owner       = "my-org"
      repo        = "api-service"
      workflow_id = 12345678
    }
  }
}

resource "ctrlplane_deployment_system_link" "api" {
  deployment_id = ctrlplane_deployment.api.id
  system_id     = ctrlplane_system.example.id
}
See Deployments for the full reference on properties, versions, variables, and more.

​
Policies

Policies control how releases flow through environments:

Approval

Require sign-off before deployment

Environment Progression

Gate production on staging success

Gradual Rollouts

Stagger deployments across targets

Verification

Validate deployment health

Deployment Dependency

Enforce ordering between deployments

Deployment Window

Time-based deployment scheduling

Version Cooldown

Batch frequent releases

Version Selector

Control which versions can deploy

Retry

Automatic retry on failure

​
Job Agents

Execute deployments on your infrastructure:

GitHub Actions

Trigger workflow dispatch

ArgoCD

GitOps deployments

Terraform Cloud

Infrastructure as code

​
Key Benefits

BenefitDescription
Consistent processSame workflow for all deployments
Policy enforcementGates prevent unauthorized releases
VisibilityTrack what’s deployed where
Automatic rollbackFailed verification triggers rollback

​
Next Steps