gcloud run deploy: Usage, Flags & Common CI Errors

Deploy a container or source to Cloud Run with one command.

gcloud run deploy creates or updates a Cloud Run service from a container image (or builds from source). It handles revisions, traffic, scaling, and environment - the core deploy step for serverless containers on GCP.

What it does

gcloud run deploy <service> --image <uri> rolls out a new revision from an image, sets env vars, CPU/memory, concurrency, and routes traffic. With --source it builds the image from your code via Cloud Build first. --region is required (or set run/region), and --allow-unauthenticated makes the service public.

Common usage

# Deploy from a prebuilt image
gcloud run deploy my-svc \
  --image us-central1-docker.pkg.dev/my-project/repo/my-svc:latest \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "ENV=prod"

# Build from source and deploy
gcloud run deploy my-svc --source . --region us-central1

Common error in CI: "container failed to start / listen on PORT" or permission denied

Deploys fail with "The user-provided container failed to start and listen on the port defined provided by the PORT=8080 environment variable" when the app hardcodes a port instead of reading $PORT, or "Permission denied" when the deployer lacks roles/run.admin and iam.serviceAccountUser. Fix: have the app listen on the $PORT env var (Cloud Run sets it, default 8080); grant the CI identity run.admin on the service and serviceAccountUser on the runtime service account; ensure the image exists and is readable by Cloud Run.

Key options

Related guides