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 Docker with the Buildx plugin enabled.
Starting with CLI v3.7.2, cpln image build requires Docker Buildx. Verify Buildx is available: 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 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
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
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. 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
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.0my-org.registry.cpln.io/frontend:latestmy-org.registry.cpln.io/worker:abc123 Push steps
Authenticate Docker
Configure Docker to authenticate with your org’s registry: 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.ioUsername <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): 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-nam e > .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 For common issues with building and pushing images, see Images Troubleshooting .
Next steps 
