Google Cloud Build Explained: GCP's Managed CI/CD Service

Simple explanation

Think of Cloud Build as a recipe runner for your code. When you push a commit to GitHub, Cloud Build wakes up, reads the recipe (your cloudbuild.yaml), and follows each instruction in order.

Each instruction runs inside its own container. One step might run your test suite using a Python container. The next builds your Docker image. Another pushes it to Artifact Registry. The last deploys it to Cloud Run. Each container is clean and disposable — there is no shared state between steps unless you use the shared /workspace directory, which Cloud Build mounts automatically.

The key thing to understand: you are not configuring a server. Google provides the execution environment, scales it to zero when you are not building, and handles all the underlying infrastructure. Your job is to write the pipeline config and grant the build service account the right permissions.

Why Cloud Build matters

The obvious benefit is not having to manage CI servers. Jenkins, self-hosted GitLab runners, TeamCity: all require a machine, an OS, security patches, and someone to maintain them. Cloud Build eliminates that entirely.

The more important benefit is environment cleanliness. Every Cloud Build job runs in a completely fresh environment. There is no leftover state from a previous build: no old package cache, no residual credentials, no zombie processes. This alone eliminates a large category of intermittent CI failures that are genuinely difficult to reproduce and debug on shared runners.

Cloud Build also integrates natively with the rest of GCP. The build service account can push to Artifact Registry, deploy to Cloud Run, update GKE clusters, or pull secrets from Secret Manager, all using IAM with no third-party credential management needed.

On cost: Cloud Build includes 120 free build-minutes per day on the default machine type. For most small to mid-sized teams, this covers a reasonable share of CI activity. Beyond the free tier, you pay per build-minute based on machine type.

How Cloud Build works

Here is the end-to-end flow from a code push to a deployed application:

1. A change occurs. A developer pushes a commit to a branch, opens a pull request, or pushes a git tag. This is the event that starts everything.
2. A trigger evaluates the event. Cloud Build checks whether any configured trigger matches. If the event matches, the trigger fires and a build starts.
3. Cloud Build fetches the source. It pulls the repository at the matching commit into the build environment. Source checkout is handled automatically. You do not need a git step in your pipeline config.
4. Steps execute in order. Cloud Build reads your cloudbuild.yaml and runs each step. Each step is a container that runs a command. Steps run sequentially by default. Use waitFor to express dependencies and enable parallel execution.
5. Artifacts are produced. A typical build produces a container image tagged with the commit SHA. Cloud Build pushes it to Artifact Registry so you can trace exactly which code version is running anywhere.
6. Deployment runs (optional). A final step can deploy the image to Cloud Run, GKE, or hand off to Cloud Deploy for controlled multi-environment delivery.
7. Logs and status are visible. Build logs stream to Cloud Logging in real time. The trigger status reports back to GitHub as a commit or pull request check.

All steps share the /workspace directory, which Cloud Build mounts as a volume. Files written there in one step are available to subsequent steps. Nothing outside /workspace persists between steps.

Core concepts

Build steps

A step is the fundamental unit in a Cloud Build pipeline. Each step specifies a container image (name), the command to run inside it, and an optional id for referencing the step in waitFor dependencies. Steps run sequentially unless you use waitFor to express a different order.

steps:
  - name: 'python:3.11'
    entrypoint: bash
    args: ['-c', 'pip install -r requirements.txt && python -m pytest tests/']
    id: run-tests

  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'europe-west2-docker.pkg.dev/$PROJECT_ID/app/api:$SHORT_SHA', '.']
    id: build-image
    waitFor: ['run-tests']

Using waitFor: [’-’] tells Cloud Build to start a step immediately at build start, without waiting for any prior steps. This is useful for running independent checks in parallel and cutting overall build time.

Triggers

A trigger connects a git event to a build. Three trigger types are available:

• Push to branch: fires when a commit is pushed to a branch matching a pattern. Use this for continuous integration on main or develop.
• Push new tag: fires when a tag matching a pattern is pushed, for example v*. Use this for release pipelines where a version tag triggers a production image build.
• Pull request: fires when a PR is opened or updated. Use this to run tests and analysis before merging. Requires a GitHub App connection. By default, Cloud Build only runs PR builds from trusted contributors, which prevents untrusted code from accessing the build environment and any secrets it contains.

Triggers can also be invoked manually via the Cloud Console, gcloud CLI, or the Cloud Build API, which is useful for one-off deployments or debugging a specific commit.

Substitutions

Cloud Build provides built-in variables you can reference in any step argument:

• $PROJECT_ID: your GCP project ID
• $SHORT_SHA: the first 7 characters of the triggering commit SHA. Use this for image tags.
• $COMMIT_SHA: the full commit SHA
• $BRANCH_NAME: the branch that triggered the build
• $TAG_NAME: the git tag, for tag triggers
• $REPO_NAME: the repository name

You can define custom substitutions in the trigger configuration or build config, prefixed with an underscore: $_ENV, $_REGION. Custom substitutions make a single pipeline config reusable across projects and environments without duplicating files.

Builder images

Any Docker container image can serve as a build step. Google maintains official builders for common tasks:

• gcr.io/cloud-builders/docker: Docker CLI for building, tagging, and pushing images
• gcr.io/google.com/cloudsdktool/cloud-sdk: gcloud, gsutil, bq, and kubectl. Use this for any step that runs gcloud commands.
• gcr.io/cloud-builders/kubectl: kubectl for GKE deployments
• gcr.io/cloud-builders/git: git CLI, for pipelines that need it

For language-specific steps, use any public image: node:20-alpine, python:3.12-slim, golang:1.22. You can also build your own custom builder image and host it in Artifact Registry for internal tooling shared across pipelines.

Service account and permissions

Cloud Build runs as a service account. By default, a project has a Cloud Build default service account. You can also specify a custom service account per trigger or per build, which is recommended for pipelines that need different permission boundaries.

The service account needs IAM roles for every action the pipeline performs. A pipeline that pushes images and deploys to Cloud Run needs these three roles at minimum:

• roles/artifactregistry.writer: to push images
• roles/run.developer: to deploy Cloud Run services
• roles/iam.serviceAccountUser: to act as the Cloud Run service identity

Never grant roles/editor to a build service account. See the secure CI/CD pipelines guide for a thorough walkthrough of least-privilege setup and Workload Identity Federation for builds initiated from GitHub.

A complete example pipeline

This pipeline runs tests, builds and pushes a container image to Artifact Registry, then deploys to Cloud Run. Each stage depends on the one before it. A test failure stops the pipeline before an image is ever built.

steps:
  # Step 1: Run unit tests — stop the build here if anything fails
  - name: 'python:3.11'
    entrypoint: bash
    args:
      - -c
      - |
        pip install -r requirements.txt
        python -m pytest tests/ -v
    id: run-tests

  # Step 2: Build the image, tagged with the commit SHA for traceability
  - name: 'gcr.io/cloud-builders/docker'
    args:
      - build
      - -t
      - europe-west2-docker.pkg.dev/$PROJECT_ID/api/api:$SHORT_SHA
      - -t
      - europe-west2-docker.pkg.dev/$PROJECT_ID/api/api:latest
      - .
    id: build-image
    waitFor: ['run-tests']

  # Step 3: Push both tags to Artifact Registry
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', '--all-tags', 'europe-west2-docker.pkg.dev/$PROJECT_ID/api/api']
    id: push-image
    waitFor: ['build-image']

  # Step 4: Deploy the SHA-tagged image to Cloud Run
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    args:
      - gcloud
      - run
      - deploy
      - api-service
      - --image=europe-west2-docker.pkg.dev/$PROJECT_ID/api/api:$SHORT_SHA
      - --region=europe-west2
      - --platform=managed
    waitFor: ['push-image']

images:
  - 'europe-west2-docker.pkg.dev/$PROJECT_ID/api/api:$SHORT_SHA'

options:
  logging: CLOUD_LOGGING_ONLY
  machineType: E2_HIGHCPU_8

A few things worth noting here:

• The deployment step uses $SHORT_SHA rather than latest. This means you can see exactly which commit is running in Cloud Run and roll back to a specific version if needed.
• logging: CLOUD_LOGGING_ONLY sends build logs to Cloud Logging rather than a GCS bucket. Easier to query, and keeps logs alongside your application logs.
• machineType: E2_HIGHCPU_8 upgrades from the default 1 vCPU machine. For larger images or longer test suites, upgrading the machine type can cut build times considerably.

Setting up service account permissions

Before your pipeline can push images or deploy services, the build service account needs the right roles. Run the following to identify the active service account and grant it:

# Get the Cloud Build default service account for your project
CB_SA=$(gcloud builds get-default-service-account --project=my-app-prod)

# Allow pushing images to Artifact Registry
gcloud projects add-iam-policy-binding my-app-prod \
  --member="serviceAccount:${CB_SA}" \
  --role="roles/artifactregistry.writer"

# Allow deploying Cloud Run services
gcloud projects add-iam-policy-binding my-app-prod \
  --member="serviceAccount:${CB_SA}" \
  --role="roles/run.developer"

# Required to act as the Cloud Run service identity
gcloud projects add-iam-policy-binding my-app-prod \
  --member="serviceAccount:${CB_SA}" \
  --role="roles/iam.serviceAccountUser"

When to use Cloud Build

Cloud Build is a practical fit when:

• You are building and deploying container images to GCP. Building an image, pushing it to Artifact Registry, and deploying it to Cloud Run or GKE fits naturally into a single pipeline. This is the core use case.
• You want tests to run on every commit. Connect a trigger to your main branch, define a test step, and Cloud Build handles the rest. Failed tests show up as failed builds in the console and as a GitHub commit status.
• Your team works primarily within GCP. Cloud Build integrates with GCP services without third-party credential management. The build service account authenticates with IAM. There are no API tokens to rotate or store externally.
• You do not want to maintain CI infrastructure. No servers, no agents, no OS updates, no downtime. Cloud Build scales automatically and requires zero maintenance beyond the pipeline config itself.
• You need native secrets integration. Cloud Build integrates with Secret Manager via the availableSecrets block. Secrets are injected into step environments at runtime and never stored in config files or build logs. See secrets in CI/CD pipelines for practical examples.
• You are setting up CI/CD for Cloud Run. The CI/CD pipelines for Cloud Run guide shows how Cloud Build fits into a complete end-to-end pipeline for Cloud Run services specifically.

When Cloud Build may not be the best fit

Cloud Build is not the right tool for every situation.

• Your organisation is standardised on another CI platform. If your team runs Jenkins, CircleCI, or GitLab CI across all projects, adding Cloud Build creates fragmentation and doubles the surface area your team needs to understand. It is usually better to extend the existing platform with GCP integration than to introduce a second CI system.
• You need complex multi-environment delivery. Cloud Build can run deployments, but it has no native concept of environments, promotion workflows, or approval gates. For controlled delivery across dev, staging, and production, use Cloud Deploy, which is purpose-built for that problem.
• You have strict VPC networking requirements. Standard Cloud Build jobs run on Google-managed infrastructure and make outbound internet calls. If your pipeline needs to reach private resources on a VPC, a private worker pool is required, which adds configuration complexity and cost.
• You deploy to multiple cloud providers. Cloud Build is Linux-only and GCP-focused. If your delivery process spans AWS, Azure, or on-premises targets, a cross-platform tool like GitHub Actions gives you more flexibility.
• Portability across CI systems matters. Cloud Build config files are not portable to other platforms. If you want pipelines that can run locally or on any CI system, something closer to a portable standard (Tekton, which Cloud Build is built on, or Makefile-driven workflows) may suit better.

Cloud Build vs GitHub Actions

Both tools can build containers, run tests, and deploy to GCP. The decision usually comes down to where your team lives and what you are deploying to.

Where Cloud Build has an advantage

• Native GCP IAM integration: the build service account authenticates automatically with Artifact Registry, Cloud Run, and GKE without managing API keys or extra Workload Identity setup
• Build logs go directly to Cloud Logging alongside application logs, in the same tooling your team already uses for observability
• No GitHub Actions minutes consumed for GCP deployments, which can be more cost-effective for GCP-heavy teams
• Tighter integration with Cloud Deploy for multi-environment delivery with approval gates
• Build history and audit trail are retained inside GCP, subject to the same access controls as your other GCP resources

Where GitHub Actions has an advantage

• Simpler setup if your code is already on GitHub and you want a single system for both code review and CI
• Vast marketplace of pre-built actions for third-party services: Slack notifications, Jira updates, Terraform, and hundreds more
• macOS and Windows runners for cross-platform builds and mobile CI
• Better suited for workflows that span multiple cloud providers or on-premises infrastructure
• Pull request automation — comment-triggered builds, label-based workflows, and PR preview environments — is more mature

Choosing between them

Choose Cloud Build if your team is GCP-native, your targets are Cloud Run and GKE, and you want tight IAM integration with Secret Manager without additional credential setup.

Choose GitHub Actions if you are already on GitHub, you deploy to multiple platforms, or you want access to the community actions ecosystem.

Using both together

Many teams run both. GitHub Actions handles pull request checks — linting, formatting, unit tests — because these do not need GCP resources and benefit from the native GitHub PR status integration. Cloud Build handles GCP-specific steps: image builds, registry pushes, and deployments. This avoids granting GitHub Actions broad GCP permissions while keeping CI feedback visible on GitHub commits and PRs.

Best practices

• Use least privilege for the build service account. Grant only the roles your pipeline needs. Review and remove any roles added for debugging. Consider a dedicated service account per pipeline rather than the project default, so different pipelines cannot access each other’s resources.
• Tag images with commit SHAs. Always include $SHORT_SHA in your image tags. This gives you a traceable link between a running container and the code that produced it, and makes rollbacks straightforward.
• Put your test step first and fail fast. There is no point building and pushing an image if the tests fail. A failed test step stops the pipeline immediately and saves build minutes.
• Keep secrets in Secret Manager. Use the availableSecrets block to inject secrets as environment variables at runtime. Secrets handled this way do not appear in logs, config files, or build history.
• Use custom substitutions for environment differences. Define $_REGION, $_PROJECT, and similar variables in your trigger configuration rather than hardcoding values. This makes a single pipeline config reusable across dev and production builds.
• Set logging: CLOUD_LOGGING_ONLY. This sends logs to Cloud Logging rather than a GCS bucket, making them easier to query and available alongside your application logs in the same tooling.
• Use Cloud Deploy for multi-environment delivery. If you are promoting builds through dev, staging, and production, move the deployment concern to Cloud Deploy. Keep Cloud Build focused on producing a tested, tagged artifact. Cloud Build creates the release; Cloud Deploy delivers it.
• Link builds to deployments using the commit SHA. Use $SHORT_SHA as the image tag and, when creating a Cloud Deploy release, as part of the release name. This creates a complete audit trail from commit to deployment that you can trace in either direction.

Frequently asked questions

What is Cloud Build used for?

Cloud Build automates the steps between a code commit and a running application. Typical uses are: running tests on every commit, building container images and pushing them to Artifact Registry, and deploying to Cloud Run or GKE. It handles both CI and simple CD in a single managed service, with no infrastructure to maintain.

Is Cloud Build a CI tool or a CD tool?

Both, depending on how you configure it. Cloud Build is primarily a CI tool: it runs automated build and test steps on every code change. It can also deploy (CD), but for complex multi-environment delivery with promotion workflows and approval gates, Google recommends pairing it with Cloud Deploy. The two services are designed to complement each other, not replace one another.

What is the difference between Cloud Build and Cloud Deploy?

Cloud Build runs the steps that produce an artifact: tests, image builds, registry pushes. Cloud Deploy handles the controlled delivery of that artifact through environments — dev, staging, production — with promotion workflows, approval gates, and rollback. Cloud Build ends when the image is tested and pushed. Cloud Deploy takes over from there. You typically trigger a Cloud Deploy release as the last step of a Cloud Build pipeline.

Does Cloud Build replace GitHub Actions?

Not necessarily. Cloud Build integrates natively with GCP services using IAM and requires no credential management for GCP targets. GitHub Actions works across any platform and has a broader third-party ecosystem. Many teams use both: GitHub Actions for PR feedback checks, Cloud Build for GCP-specific build and deployment steps. See the comparison section above and the GitHub Actions for GCP guide for help deciding.

What permissions does Cloud Build need?

Cloud Build runs as a service account. Grant only the roles your pipeline actually uses. For a standard build-and-deploy pipeline: roles/artifactregistry.writer to push images, roles/run.developer to deploy Cloud Run services, and roles/iam.serviceAccountUser to act as the Cloud Run service identity. Find the active service account with gcloud builds get-default-service-account. Never grant roles/editor to a build service account.