Google Cloud Deploy Explained: Managed Continuous Delivery for GCP

Simple explanation

If you are new to CI/CD, it helps to separate two distinct jobs in the pipeline.

Cloud Build takes your source code, runs tests, builds a container image, and pushes it to Artifact Registry. That is the CI part. Its job is to produce a verified, deployable artifact.

Cloud Deploy takes that artifact and moves it through your environments. Dev gets it first. If that passes, the same artifact moves to staging. After staging, it promotes to production. That is the CD part.

The key idea is that you create one release and promote it. You are not rebuilding or re-deploying from scratch at each stage. The exact image SHA that ran in dev is what ends up in production. This is what gives you confidence that what you tested is what you shipped.

What problem Cloud Deploy solves

Building a container image in CI is just the start. You still need to move it from dev to staging to production in a controlled, auditable way. Without a dedicated CD system, teams build their own delivery process out of shell scripts, Slack messages, and manual steps that nobody fully documents. Each person who touches deployments knows a slightly different version of how it works.

The problems that follow are predictable. Deployments to production look different from deployments to staging because someone added a step and forgot to update the rest. There is no central record of what was deployed where and when. Rolling back means hunting for the previous image tag and hoping someone remembers the correct command. Production approval lives in a chat thread where it is easy to miss or bypass under pressure.

Cloud Deploy gives you a first-class deployment pipeline with a release history, promotion workflow, approval gates, and rollback built in. You define the pipeline once in YAML and it applies consistently to every release from that point forward.

How Cloud Deploy works

Here is the end-to-end flow from a code push to a production deployment:

1. Code is pushed and a Cloud Build trigger fires.
2. Cloud Build builds and tests the application, then pushes a container image to Artifact Registry.
3. Cloud Build creates a Cloud Deploy release as its final step. The release captures the specific image tag to deliver.
4. Cloud Deploy deploys the release to the first target, usually dev, immediately after creation.
5. A team member reviews the dev deployment and promotes the release to staging. Cloud Deploy deploys the same image to the staging target.
6. After staging passes, the team promotes to production. If the production target has an approval gate, Cloud Deploy pauses and notifies approvers.
7. An approver signs off in the console or CLI. Cloud Deploy proceeds with the production rollout.
8. Every rollout is recorded in Cloud Deploy’s history. If something goes wrong, re-deploying a previous release takes one command.

The pipeline runs the same process for every release. There is no special treatment for hotfixes or urgent deploys. That consistency is the point. See Rollbacks in Cloud Deploy for how to recover when a production deployment needs to be reversed.

Key concepts

Delivery pipeline

A delivery pipeline defines the ordered sequence of environments a release moves through, typically dev, staging, and then production. Each stage in the pipeline points to a target. You create one pipeline per application or service and apply it once with gcloud. Every future release uses the same pipeline.

Target

A target is a deployment destination: a specific Cloud Run service, a GKE cluster, or an Anthos cluster. Each target represents one environment. Targets can live in different GCP projects, which is the recommended setup for proper environment isolation. Keeping dev, staging, and prod in separate projects limits blast radius if something goes wrong. This is covered in more detail on managing environments in CI/CD.

Release

A release is an immutable snapshot of what you want to deploy, typically a specific container image tag resolved to a SHA digest. You create a release once. The same image SHA that is tested in staging is what gets promoted to production. There is no ambiguity about what is running where, and no possibility of a silent change between environments.

Rollout

A rollout is the act of deploying a release to a specific target. Each time you promote a release to a new environment, Cloud Deploy creates a new rollout. Every rollout’s status, logs, and approvals are retained in the deployment history, giving you a complete record of what happened and when.

When to use Cloud Deploy

Cloud Deploy is a good fit when any of the following apply to your project:

• You have multiple environments and need to promote the same release through all of them
• You need a human approval gate before production deployments
• Audit trails matter, such as for compliance, incident investigation, or regulated environments
• Your team wants to separate who can trigger deployments from who can approve them
• Dev, staging, and prod live in different GCP projects and you want a consistent deployment process across all three
• You are deploying to Cloud Run, GKE, or Anthos and want built-in support for canary or blue-green delivery strategies

Cloud Deploy is also a natural fit if your team is growing and you want to replace informal deployment practices with something that scales reliably without depending on one person’s knowledge.

When Cloud Deploy may be unnecessary

Not every project needs a full CD platform. Cloud Deploy adds operational overhead that is not always justified. Consider skipping it when:

• Your application has a single environment with no need for staged promotion
• The deployment is a small internal tool with low risk if something goes wrong
• Your team is one or two people and maintaining pipeline YAML outweighs the benefit
• Direct deployment from Cloud Build to Cloud Run is fast, simple, and sufficient

For those situations, deploying directly from Cloud Build is a simpler and entirely reasonable choice. The next section explains where the line falls.

Cloud Deploy vs Cloud Build

This is the most common source of confusion when starting with GCP’s delivery tooling. The short answer is that they are not competing products. They solve different problems and are designed to be used together.

The typical setup is: Cloud Build handles everything up to and including pushing the image, then hands off to Cloud Deploy for the controlled delivery. Read the Cloud Build overview for a full picture of what Cloud Build does before Cloud Deploy takes over.

Cloud Deploy vs direct deployment from Cloud Build

Cloud Build can deploy directly to Cloud Run or GKE using a gcloud step in cloudbuild.yaml. This is simpler to set up and works well for many projects. So when does Cloud Deploy become the better choice?

Direct deployment from Cloud Build is sufficient when:

• You deploy to one environment only
• You do not need approval gates or a deployment history
• Speed of setup matters more than process rigour
• The application is not user-facing or has low risk if a bad deploy goes out

Cloud Deploy becomes the right choice when:

• You need the same image to move through dev, staging, and prod without rebuilding
• You want a production approval gate enforced by the platform, not just by convention
• You need a permanent record of what was deployed to each environment and by whom
• You want built-in support for canary or blue-green traffic management

Direct Cloud Build deployments are covered in detail on the Deploying with Cloud Build page if you want to compare the setup side by side.

Configuring a delivery pipeline

You define your delivery pipeline and targets in YAML, then apply them with gcloud. The example below creates a three-stage pipeline with dev, staging, and prod, each pointing to a separate GCP project for proper environment isolation. The prod target requires manual approval before any rollout can proceed.

# clouddeploy.yaml
apiVersion: deploy.cloud.google.com/v1
kind: DeliveryPipeline
metadata:
  name: api-pipeline
  location: europe-west2
description: "API service delivery pipeline"
serialPipeline:
  stages:
    - targetId: dev
    - targetId: staging
    - targetId: prod
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
  name: dev
  location: europe-west2
run:
  location: "projects/my-app-dev/locations/europe-west2"
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
  name: staging
  location: europe-west2
run:
  location: "projects/my-app-staging/locations/europe-west2"
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
  name: prod
  location: europe-west2
requireApproval: true
run:
  location: "projects/my-app-prod/locations/europe-west2"

# Apply the pipeline and target configuration
gcloud deploy apply --file=clouddeploy.yaml --region=europe-west2 --project=my-app-prod

Using separate GCP projects for each environment is recommended because it gives you proper IAM isolation. A misconfiguration in dev cannot affect production resources when they live in entirely separate projects.

The requireApproval: true field on the prod target is a built-in change management gate. Cloud Deploy pauses the rollout and notifies the configured approvers. No deployment proceeds until someone approves it explicitly in the console or via the API. This is a simple and effective complement to the broader practices covered on secure CI/CD pipelines.

Creating and promoting releases

Once the pipeline is configured, you create a release by pointing Cloud Deploy at the image you want to deliver. Cloud Deploy immediately deploys it to the first stage. The $SHORT_SHA variable comes from Cloud Build and gives each release a unique, traceable name tied to the specific commit.

# Creates a release and deploys to dev immediately
gcloud deploy releases create api-release-$SHORT_SHA \
  --delivery-pipeline=api-pipeline \
  --region=europe-west2 \
  --images=api=europe-west2-docker.pkg.dev/my-app-prod/api/api:$SHORT_SHA

After dev passes, promote the same release to staging. You are not creating a new release. You are moving the existing one forward through the pipeline.

gcloud deploy releases promote \
  --release=api-release-$SHORT_SHA \
  --delivery-pipeline=api-pipeline \
  --region=europe-west2 \
  --to-target=staging

After staging passes, promote to prod. Because the prod target has requireApproval: true, Cloud Deploy pauses. An approver then signs off via the console or the CLI:

gcloud deploy rollouts approve api-release-$SHORT_SHA-to-prod-0001 \
  --delivery-pipeline=api-pipeline \
  --region=europe-west2

Integrating with Cloud Build

The standard pattern: Cloud Build handles everything up to and including the image push, then creates a Cloud Deploy release as its final step. Cloud Deploy takes over from there and manages the journey to production.

This keeps responsibilities clean. Cloud Build owns the artifact. Cloud Deploy owns the delivery. The image is pushed to Artifact Registry first, and the release is created with a reference to that specific image tag, so there is no ambiguity about which version is being delivered.

# cloudbuild.yaml
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'europe-west2-docker.pkg.dev/my-app-prod/api/api:$SHORT_SHA', '.']

  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'europe-west2-docker.pkg.dev/my-app-prod/api/api:$SHORT_SHA']

  # Hand off to Cloud Deploy for controlled delivery
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    args:
      - gcloud
      - deploy
      - releases
      - create
      - api-release-$SHORT_SHA
      - --delivery-pipeline=api-pipeline
      - --region=europe-west2
      - --images=api=europe-west2-docker.pkg.dev/my-app-prod/api/api:$SHORT_SHA

For a full walkthrough of setting up this pattern for a Cloud Run service, see CI/CD pipelines for Cloud Run. If you are building Docker images in Cloud Build before this step, building Docker images with Cloud Build covers the build step in detail.

Approval gates and deploy parameters

Approval gates are the simplest built-in safety mechanism Cloud Deploy offers. Add requireApproval: true to any target and the pipeline pauses there until someone explicitly approves or rejects the rollout. Use it on production as a minimum. For critical services where a bad staging deployment could cascade into wider problems, consider adding it to staging too.

When a rollout is waiting for approval, Cloud Deploy can notify via Pub/Sub if you have configured notifications. Approvers can act in the Cloud Console, the gcloud CLI, or the REST API. The approval event is logged in the rollout history alongside the approver’s identity.

Deploy parameters let you pass configuration values at release creation time and reference them in your Kubernetes manifests or Cloud Run configuration. This makes it possible to use different settings per environment without maintaining separate manifest files for each one:

gcloud deploy releases create api-release-v2 \
  --delivery-pipeline=api-pipeline \
  --region=europe-west2 \
  --deploy-parameters="MIN_INSTANCES=2,MAX_INSTANCES=50"