CI/CD Usage

Automate deployments and resource management with the Control Plane CLI in CI/CD pipelines.

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

   npm install -g @controlplane/cli@<version>
   cpln --version
   

   Binary

   Download and extract the binary for your platform. See Installation.

   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

Console

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)

CLI

cpln serviceaccount create --name ci-pipeline --description "CI/CD automation"

Add to a group:

cpln group add-member <group-name> --serviceaccount ci-pipeline

Generate a key

Create an authentication key for the service account:

Console

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

CLI

cpln serviceaccount add-key ci-pipeline --description ci-pipeline-key

Save the returned 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)

Optional but recommended

• CPLN_ORG - Default organization
• CPLN_GVC - Default GVC

Optional

• CPLN_SKIP_UPDATE_CHECK - Any non-empty value opts out of the CLI’s daily new-version check and the notice it prints

GitHub Actions

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 --push 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: the registry is <org>.registry.cpln.io, the username is the literal string <token>, and the password is the service account key.

Building remotely is also available: cpln image build --name <image-name>:<image-tag> --remote uploads the build folder, and the image is built and pushed to the org registry with only CPLN_TOKEN and CPLN_ORG (or --org) — no daemon and no docker-credential-cpln, though the local build options (--dockerfile, --builder, --buildpack, --env, --platform) do not apply. With --repo <https-url>, the remote build clones a GitHub or GitLab repository instead of uploading the folder.

For a private repository, run that command once from your own terminal: the CLI opens the provider’s authorization page and continues the build once you grant the org access to the repository. The connection is bound to the org, so from then on pipelines build that repository without any further prompting. A pipeline cannot do this first run itself — with no terminal attached, the CLI prints the connect link and stops.

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 -

Resource ordering

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.

Multi-document YAML

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

Handling renames

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:

Console

Use the Export action to download JSON or YAML.

CLI

bash

cpln gvc get <name> --output yaml-slim > gvc.yaml
cpln workload get <name> --gvc <gvc> --output yaml-slim > workload.yaml
cpln secret get <name> --output yaml-slim > secret.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

Pin the CLI version

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.

Use dedicated service accounts

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.

Store secrets securely

• 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

Test in non-production first

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

Use slim output for templates

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

Authentication failures

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

Wrong org or GVC

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