Push Images to Registry

Push container images to your organization’s private registry on Control Plane. Use Docker, the CLI, or any Docker-compatible client.

When to use this

CI/CD pipelines

Build and push images in automated pipelines

Local development

Push locally-built images for testing

Private registry

Store images in your org’s secure registry

No Dockerfile

Build automatically with buildpacks

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Docker installed

Install Docker. The Buildx plugin is recommended (used by default when available) but no longer required for single-platform builds.Docker is only needed for local builds; cpln image build --remote builds remotely instead.

Required permissions

You need push permission on images. See Image Permissions.

Docker Buildx (recommended)

As of CLI v3.7.2, cpln image build uses docker buildx build. As of CLI v3.9.0, it falls back to legacy docker build when Buildx is unavailable, so Buildx is optional for single-platform builds. Multi-platform builds (comma-separated --platform values) still require Buildx.Verify Buildx is available:

docker buildx version

If not installed, add the plugin:

BUILDX_VERSION=v0.29.1
curl -sSL "https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64" \
  | install -m 0755 -D /dev/stdin ~/.docker/cli-plugins/docker-buildx

Build and push

Using the CLI (Recommended)
Using Docker directly

Best for: Local development, CI/CD pipelines, buildpack builds

Authenticates to your org’s private registry automatically
Simple naming (--name my-app:v1)
Supports Dockerfile or Buildpacks
Builds remotely without Docker (--remote)

With a Dockerfile

The Dockerfile is automatically detected (defaults to ./Dockerfile):

cpln image build --name my-app:v1 --push

Or specify a different path:

cpln image build --dockerfile ./path/to/Dockerfile --name my-app:v1 --push

Learn more about working with images: CLI images guide | Command reference

With build arguments

Pass a value the Dockerfile reads with ARG, either directly or from your environment:

cpln image build --name my-app:v1 --push \
  --build-arg NODE_VERSION=22 \
  --build-arg GIT_SHA

See Build Arguments for the forms it accepts.

With a private registry or other build credential

A build that installs from a private package registry needs a credential during the build, but not in the finished image. Store it as a secret in your org and mount it for the step that needs it:

# Once: store the credential
cpln secret create-opaque --name npm-token --file ./npm-token.txt --encoding plain

# Every build: mount it for a single RUN step
cpln image build --name my-app:v1 --push \
  --secret id=npmtoken,src=cpln://secret/npm-token

RUN --mount=type=secret,id=npmtoken,required=true \
    NPM_TOKEN="$(cat /run/secrets/npmtoken)" npm ci

The value is mounted for that step only, so it never lands in the image or its layers. See Build Secrets.

Do not pass a credential with --build-arg or --env. Those values become part of the image and can be recovered by anyone who can pull it.

With Buildpacks

Build automatically without a Dockerfile:

cpln image build --name my-app:v1 --push

Buildpacks detect your language and create an optimized image. See Buildpacks conventions for language-specific requirements.

Without Docker

Add --remote to build remotely; the image is pushed for you:

cpln image build --name my-app:v1 --remote

Or build a repository directly:

cpln image build --name my-app:v1 --remote --repo https://github.com/my-org/my-app --branch main

See Remote builds for details.

Best for: Existing Docker workflows, custom build processes, external CI/CD systems

Requires manual authentication
Must use full registry path: ORG.registry.cpln.io/IMAGE:TAG

Image name format

When using Docker directly, images must use this format:

ORG_NAME.registry.cpln.io/IMAGE_NAME:TAG

Examples:

my-org.registry.cpln.io/api:v1.0.0
my-org.registry.cpln.io/frontend:latest
my-org.registry.cpln.io/worker:abc123

Push steps

Authenticate Docker

Configure Docker to authenticate with your org’s registry:

cpln image docker-login

This uses your default CLI profile. Set CPLN_PROFILE to use a different profile.

Build the image

Build with the correct tag format:

docker buildx build --platform=linux/amd64 \
  -t my-org.registry.cpln.io/my-app:v1 .

Always target linux/amd64 to ensure compatibility with Control Plane.

Tag an existing image (optional)

If you have an existing image, tag it for your registry:

docker tag my-app:v1 my-org.registry.cpln.io/my-app:v1

Push to registry

docker push my-org.registry.cpln.io/my-app:v1

CI/CD authentication

For CI/CD pipelines without the CLI, authenticate with a service account:

echo $SERVICE_ACCOUNT_KEY | docker login my-org.registry.cpln.io -u '<token>' --password-stdin

Parameter	Value
Registry	`ORG_NAME.registry.cpln.io`
Username	`<token>` (literal string)
Password	Service account key

Store the service account key securely. If compromised, delete and regenerate it.

See Create a Service Account for key generation.

Reference images in workloads

Once pushed, reference your images in workloads using the Control Plane image link format.

Important: Do not use the Docker registry path (org.registry.cpln.io/...) in workload configurations. Always use the Control Plane image link format shown below.

Shorthand format (recommended):

//image/IMAGE_NAME:TAG

Full format:

/org/ORG_NAME/image/IMAGE_NAME:TAG

Example workload configuration:

containers:
  - name: my-container
    image: //image/my-app:v1

Or with the full path:

containers:
  - name: my-container
    image: /org/my-org/image/my-app:v1

In the console, press Ctrl+I when configuring a workload to browse available images.

Common workflows

Build and deploy

# Build and push (Authenticates automatically)
cpln image build --name my-app:v1.2.3 --push

# Update workload
cpln workload update my-app --set spec.containers<container-name>.image=//image/my-app:v1.2.3

CI/CD pipeline

# Build and push (Authenticates automatically)
cpln image build --name my-app:$CI_COMMIT_SHA --push

# Or, on a runner without a Docker daemon, build remotely
cpln image build --name my-app:$CI_COMMIT_SHA --remote

# Deploy (has the new image defined in the workload manifest container)
cpln apply --file workload.yaml

Build with a stamped revision and a private registry credential

cpln image build --name my-app:$CI_COMMIT_SHA --push \
  --build-arg GIT_SHA=$CI_COMMIT_SHA \
  --secret id=npmtoken,src=cpln://secret/npm-token

Keeping the credential in an org secret means the pipeline never holds it: no registry token in the CI variables, and nothing to rotate in the pipeline when the credential changes. The same command works on a runner without Docker by swapping --push for --remote, where the build service resolves the secret itself.

Troubleshooting

For common issues with building and pushing images, see Images Troubleshooting.

Next steps

Pull Images

Configure workloads to pull images

Copy Images

Copy images between organizations

Create a Workload

Deploy your pushed images

Image Reference

Image configuration details

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

When to use this

CI/CD pipelines

Local development

Private registry

No Dockerfile

Prerequisites

Build and push

With a Dockerfile

With build arguments

With a private registry or other build credential

With Buildpacks

Without Docker

Image name format

Push steps

CI/CD authentication

Reference images in workloads

Common workflows

Build and deploy

CI/CD pipeline

Build with a stamped revision and a private registry credential

Troubleshooting

Next steps

Pull Images

Copy Images

Create a Workload

Image Reference

​When to use this

CI/CD pipelines

Local development

Private registry

No Dockerfile

​Prerequisites

​Build and push

​With a Dockerfile

​With build arguments

​With a private registry or other build credential

​With Buildpacks

​Without Docker

​Image name format

​Push steps

​CI/CD authentication

​Reference images in workloads

​Common workflows

​Build and deploy

​CI/CD pipeline

​Build with a stamped revision and a private registry credential

​Troubleshooting

​Next steps

Pull Images

Copy Images

Create a Workload

Image Reference

When to use this

Prerequisites

Build and push

With a Dockerfile

With build arguments

With a private registry or other build credential

With Buildpacks

Without Docker

Image name format

Push steps

CI/CD authentication

Reference images in workloads

Common workflows

Build and deploy

CI/CD pipeline

Build with a stamped revision and a private registry credential

Troubleshooting

Next steps