GCP Artifact Registry Image

The gcp-artifact-registry-image recipe builds a Docker image and pushes it to Google Artifact Registry. It has no deploy step.

Use it for images that something else runs:

• Shared base images that other Dockerfiles build FROM
• Images deployed by another service, such as a Cloud Run (from image) service or a sidecar
• Tooling images used in CI or by Cloud Run Jobs managed outside Pilum

Note

Always set type: gcp-artifact-registry-image explicitly. A GCP service with only provider: gcp and no type also falls back to this recipe, so it builds and pushes but never deploys. If you meant to deploy to Cloud Run, set type: gcp-cloud-run.

Prerequisites

1. Google Cloud SDK installed and authenticated
2. Docker installed and authenticated to Artifact Registry
3. An Artifact Registry Docker repository

# Authenticate Docker to the registry host
gcloud auth login
gcloud auth configure-docker us-central1-docker.pkg.dev

# Create the repository (once)
gcloud artifacts repositories create platform-images \
  --repository-format docker \
  --location us-central1 \
  --project my-gcp-project

Service Configuration

name: go-base
type: gcp-artifact-registry-image
project: my-gcp-project
region: us-central1
registry_name: platform-images
template: go-base.dockerfile

image_name: go-base   # optional; defaults to name
version: v1.3.0       # optional; used when --tag is not given

The Dockerfile is _templates/go-base.dockerfile at the project root. This config publishes:

us-central1-docker.pkg.dev/my-gcp-project/platform-images/go-base:v1.3.0

To compile code on the host before the Docker build, add a build block as for any container recipe. Without build.cmd, the build binary step is skipped and the Dockerfile does all the work. See Build Configuration.

Required Fields

Field	Description
name	Pilum service name
project	GCP project ID
region	Artifact Registry location, e.g. us-central1, or a multi-region such as us
registry_name	Artifact Registry repository name. Use the bare name, e.g. platform-images, not a host or path.
template	Dockerfile template name, relative to _templates/

Optional Fields

Field	Type	Default	Description
image_name	string	name	Image name within the repository
version	string	latest	Image tag used when --tag is not given

Image Name and Tag

The image reference is:

<region>-docker.pkg.dev/<project>/<registry_name>/<image_name or name>:<tag>

The tag is chosen in this order:

1. --tag on the command line
2. version: in pilum.yaml
3. latest

version: lets you pin a deliberate version in source, while CI can still override it with --tag. The image is built with both the resolved tag and latest, but only the resolved tag is pushed. To move latest in the registry, run with --tag latest (or leave both --tag and version unset).

Deployment Steps

1. build binary — Runs build.cmd in the service directory (skipped when cmd is empty)
2. build docker image — docker build -f ./_templates/<template> from the project root
3. publish to registry — docker push of the resolved tag

pilum deploy and pilum publish both run all three steps. pilum build runs the first two; pilum push runs only the push.

Example Commands

# Build and push using version: from pilum.yaml
pilum deploy go-base

# Build and push a specific tag
pilum publish go-base --tag v1.4.0

# Build locally without pushing
pilum build go-base

# Preview the docker commands
pilum dry-run go-base

Generated Commands

For the configuration above, with no --tag:

docker build \
  -t us-central1-docker.pkg.dev/my-gcp-project/platform-images/go-base:v1.3.0 \
  -t us-central1-docker.pkg.dev/my-gcp-project/platform-images/go-base:latest \
  --build-arg SERVICE_NAME=services/go-base \
  -f ./_templates/go-base.dockerfile .

docker push us-central1-docker.pkg.dev/my-gcp-project/platform-images/go-base:v1.3.0

SERVICE_NAME is the service directory relative to the project root. If the service sets top-level env_vars, they are also passed to docker build through --build-arg.

Using the Image From Other Services

A Cloud Run (from image) service deploys whatever reference its image field names:

services/mcp-controller/pilum.yaml

name: mcp-controller
type: gcp-cloud-run-from-image
project: my-gcp-project
region: us-central1
image: us-central1-docker.pkg.dev/my-gcp-project/platform-images/mcp-controller:v1.0.0

Publish the image first, then deploy the services that use it, as two runs:

pilum publish mcp-controller-image --tag v1.0.0
pilum deploy mcp-controller

Caution

Don’t rely on depends_on to order these within one run. Pilum runs recipes step by step, and the from-image recipe’s deploy is its first step, so it runs alongside the image service’s build steps, before the image’s publish to registry step. depends_on orders services within each step, not across steps.

There is nothing to roll back, and pilum status, pilum logs and pilum rollback do not apply to this recipe.

Troubleshooting

Push Denied

denied: Permission "artifactregistry.repositories.uploadArtifacts" denied

Run gcloud auth configure-docker <region>-docker.pkg.dev for the repository’s host, and make sure your account has roles/artifactregistry.writer on the repository.

Repository Not Found

name unknown: Repository "platform-images" not found

Create the repository in the same region and project (see Prerequisites), and check that registry_name is the bare repository name.

Service Built but Never Deployed

If you expected a deploy, check the service’s type. This recipe has no deploy step. Use gcp-cloud-run, gcp-cloud-run-job or gcp-mig-container to deploy what you build.

Next Steps

• GCP Cloud Run (from image) — Deploy a prebuilt image
• GCP Cloud Run — Build and deploy in one pipeline
• Build Configuration — Host builds and Dockerfile templates
• Monorepo Deployments — Dependencies and waves