Skip to main content
Use the Control Plane CLI in CI/CD pipelines to automate resource provisioning, image builds, and deployments.

​
Overview

The CLI enables CI/CD workflows for:
  • Resource provisioning - Apply GVC, workload, and infrastructure configurations
  • Image delivery - Build and push container images to Control Plane
  • GitOps - Maintain infrastructure as code in version control

​
Quick start

1

Create a service account

Create a service account with appropriate permissions for your pipeline.See Create a Service Account for details.
2

Store credentials and context

Generate a key and store these environment variables in your CI/CD platform:
  • CPLN_TOKEN - The service account key (required)
  • CPLN_ORG - Your organization name (recommended)
  • CPLN_GVC - Your target GVC name (recommended)
Setting CPLN_ORG and CPLN_GVC as environment variables means you don’t need to pass --org and --gvc flags with every command.
Never print CPLN_TOKEN in logs or commit it to version control.
3

Install the CLI

Install a pinned version of the CLI in your pipeline:
npm install -g @controlplane/cli@<version>
cpln --version
Pin the CLI version for reproducible builds.
4

Create a profile

Create a default profile in your pipeline:
cpln profile create ci --default
When CPLN_TOKEN is set as an environment variable, the CLI uses it automatically.
5

Run pipeline commands

Execute CLI commands to build images and apply resources:
# Build and push image (optional)
cpln image build --name <image-name>:<image-tag> --push

# Apply resources
cpln apply --file resources.yaml

​
Service account setup

​
Create the service account

  1. Navigate to Org → Service Accounts
  2. Click Create
  3. Enter a name (e.g., ci-pipeline)
  4. Assign to a group with appropriate permissions (e.g., superusers or a custom group)

​
Generate a key

Create an authentication key for the service account:
  1. Open the service account you created
  2. Click the Keys link
  3. Enter a key description (e.g., ci-pipeline-key) and click Add
  4. Copy and download the generated key securely
Store the key in your CI/CD platform’s secret manager as CPLN_TOKEN.

​
Environment variables

Set these variables in your CI/CD platform:

​
Required

  • CPLN_TOKEN - Service account key (keep secret)
  • CPLN_ORG - Default organization
  • CPLN_GVC - Default GVC
env:
  CPLN_TOKEN: ${{ secrets.CPLN_TOKEN }}
  CPLN_ORG: my-org
  CPLN_GVC: production

​
Common pipeline workflows

​
Build and push images

# Build and push
cpln image build --name <image-name>:<image-tag> --push
cpln image build runs the build locally through Docker — a Dockerfile build shells out to docker buildx build, and a buildpacks build runs the pack CLI — so the runner needs a working Docker daemon, and --push requires docker-credential-cpln on PATH (installed alongside the CLI). On runners without a daemon (for example, GitLab runners without privileged Docker-in-Docker), build with a daemonless tool such as kaniko or buildah and push directly to the org registry instead: the registry is <org>.registry.cpln.io, the username is the literal string <token>, and the password is the service account key.

​
Apply resources (GitOps)

# Apply a single file
cpln apply --file gvc.yaml

# Apply multiple files
cpln apply --file workload.yaml --file secret.yaml

# Apply from stdin
cat resource.yaml | cpln apply --file -
A single cpln apply invocation orders resources automatically — agent, secret, cloudaccount, gvc, identity, volumeset, policy, workload, then all remaining kinds — so a workload and the GVC it references can live in the same file (or directory) in any order.Ordering only matters across separate cpln apply invocations: if you split resources into multiple pipeline steps, apply the referenced resource (e.g., the GVC) before the resource that references it.
Separate multiple resources with --- in a single file:
kind: gvc
name: my-gvc
---
kind: workload
name: my-app
Apply with:
cpln apply --file resources.yaml
Renaming a resource in YAML creates a new resource. The old resource must be deleted manually:
cpln <command> delete <old-name>

​
Export existing resources

Export “known good” configurations as templates for GitOps:
Use the Export action to download JSON or YAML.
Use json-slim or yaml-slim to remove non-essential properties like IDs, versions, and timestamps. This gives you only what’s necessary for applying the resource with cpln apply.

​
Platform-specific examples

Complete working examples for popular CI/CD platforms:

GitHub Actions

Full workflow with build, push, and apply

GitLab CI

Pipeline configuration for GitLab

Bitbucket Pipelines

Bitbucket pipeline with Docker build

CircleCI

CircleCI config with multi-stage workflow

Google Cloud Build

Cloud Build with Secret Manager

​
Best practices

Specify an exact CLI version for reproducible builds:
npm install -g @controlplane/cli@x.x.x
Update the version explicitly when you want to adopt new features.
Create separate service accounts for different environments:
  • ci-dev for development
  • ci-staging for staging
  • ci-production for production
Assign each to groups with scoped permissions.
  • Use your CI/CD platform’s secret manager
  • Never commit tokens to version control
  • Rotate service account keys regularly
  • Avoid printing CPLN_TOKEN in logs
Apply changes to development or staging environments before production:
# Staging
cpln apply --file resources.yaml --org staging

# Production (after staging succeeds)
cpln apply --file resources.yaml --org production
Export resources with yaml-slim or json-slim to remove metadata:
cpln gvc get my-gvc --output yaml-slim > gvc.yaml
This creates clean templates suitable for version control and cpln apply.

​
Troubleshooting

  1. Verify CPLN_TOKEN is set correctly in your CI/CD secrets
  2. Check the token hasn’t expired or been revoked
  3. Ensure the service account has the required permissions
Verify that the CPLN_ORG and CPLN_GVC environment variables are set correctly.Or explicitly set org and GVC in commands:
cpln apply --file workload.yaml --org my-org --gvc my-gvc
Or set in the profile:
cpln profile update ci --org my-org --gvc my-gvc
For more troubleshooting help, see the Troubleshooting page.

​
Next steps

Container Images

Use the CLI inside container images

Profiles

Learn about profile management

cpln apply

GitOps resource management guide

Service Accounts

Create and manage service accounts