gcloud builds submit: Usage & Common CI Errors

Build a container image with Cloud Build and push it - no local Docker needed.

gcloud builds submit uploads your source to Cloud Build, builds an image (or runs a cloudbuild.yaml), and pushes it to a registry. It is the serverless way to build images in CI without a Docker daemon.

What it does

The command zips the source (respecting .gcloudignore), runs the build remotely on Cloud Build, and - with --tag - builds the Dockerfile and pushes the resulting image to Artifact Registry or Container Registry. With --config it runs a multi-step cloudbuild.yaml instead.

Common usage

# Build and push to Artifact Registry by tag
gcloud builds submit \
  --tag us-central1-docker.pkg.dev/my-project/my-repo/my-app:latest

# Run a cloudbuild.yaml with substitutions
gcloud builds submit \
  --config cloudbuild.yaml \
  --substitutions _ENV=prod

Common error in CI: build SA permission denied / API not enabled

Builds fail with "Permission denied" pushing to Artifact Registry (the Cloud Build service account lacks roles/artifactregistry.writer) or "Cloud Build API has not been used in project ... before or it is disabled". Fix: enable the API (gcloud services enable cloudbuild.googleapis.com artifactregistry.googleapis.com) and grant the Cloud Build service account (PROJECT_NUMBER@cloudbuild.gserviceaccount.com) artifactregistry.writer on the target repo. Ensure the Artifact Registry repository exists first (gcloud artifacts repositories create).

Key options

Related guides