Skip to main content
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

Install the Control Plane CLI. See Installation.
Install Docker with the Buildx plugin enabled.
You need push permission on images. See Image Permissions.
Starting with CLI v3.7.2, cpln image build requires Docker 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

​
Push with the CLI

The simplest way to build and push images: 
cpln image build --name my-app:v1 --push
Or specify a Dockerfile:
cpln image build --dockerfile ./Dockerfile --name my-app:v1 --push

​
Push with Docker

1

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.
2

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.
3

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
4

Push to registry

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

​
Image name format

Images must use this format to push to your registry: 
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

​
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
ParameterValue
RegistryORG_NAME.registry.cpln.io
Username<token> (literal string)
PasswordService account key
Store the service account key securely. If compromised, delete and regenerate it.
See Create a Service Account for key generation.

​
Use pushed images

Reference pushed images in workloads: 
containers:
  - name: my-container
    image: //image/my-app:v1
Or use 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

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

​
Troubleshooting

Docker Buildx is not installed. Install it:
curl -sSL "https://github.com/docker/buildx/releases/download/v0.29.1/buildx-v0.29.1.linux-amd64" \
  | install -m 0755 -D /dev/stdin ~/.docker/cli-plugins/docker-buildx
Re-run cpln image docker-login to refresh credentials and double check that you don’t have typos in the org name.
Verify you have push permission on images. Check your policies or refresh your service account token.
Optimize your Dockerfile:
  • Use multi-stage builds
  • Start from smaller base images
  • Remove unnecessary files

​
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