Before any details, let us get one clear picture of what Cloud Build is, what it does, and why people use it.

Cloud Build is a serverless service on Google Cloud that runs your build, test, and delivery tasks. “Serverless” means you do not rent, set up, or look after any computers yourself. You hand Cloud Build a list of tasks, Google finds a machine, runs the tasks, and then throws the machine away. You pay only for the time used.

The tasks are described in a build configuration, a small text file that lists the steps to perform in order. Typical steps are: fetch the code, run automated tests, package the program into a container image, save that image in a safe storage place, and finally deploy it so people can use it.

This whole idea is called CI/CD. The letters stand for continuous integration, which means automatically combining and checking everyone’s code changes very often, and continuous delivery (or deployment), which means automatically getting the checked code to a place where it can run. Cloud Build is Google Cloud’s engine for CI/CD.

What people use it for

A handful of everyday terms from software delivery make the rest of this guide easy to follow.

Why automate at all?

Knowing how software delivery grew up explains why Cloud Build is designed the way it is.

Where it sits in Google Cloud

Cloud Build is one piece of a larger delivery toolbox. It is the “make it” engine, and it works closely with its neighbors.

• Source code hosts such as GitHub, GitLab, Bitbucket, and Google’s own source hosting tell Cloud Build when code changes.
• Artifact Registry stores the images and packages that builds produce.
• Cloud Deploy manages release stages and promotions across environments such as test, staging, and production.
• Cloud Run, Google Kubernetes Engine, App Engine, and Cloud Functions are common places to run what is built.
• Secret Manager holds passwords and keys that builds need.
• Cloud Logging and Cloud Monitoring record what happened.
• Binary Authorization can block images that were not built and approved the right way.
• Pub/Sub carries build status messages to other systems.

A small set of ideas explains almost everything Cloud Build does.

The one big idea: the machine is temporary

Each build starts on a fresh virtual machine and that machine disappears afterward. Nothing from the previous build is left behind unless you saved it somewhere permanent. This is a feature, not a flaw. It means builds are repeatable: the same input gives the same result, and leftovers from old builds cannot silently change today’s outcome.

Here is the bigger picture of how code travels from a developer’s keyboard to a running application.

flowchart LR
    DEV["Developer pushes code"] --> REPO["Source repository"]
    REPO --> TRG["Build trigger"]
    TRG --> CB["Cloud Build service"]
    CB --> POOL["Worker pool: fresh virtual machine"]
    POOL --> S1["Step 1: fetch and prepare"]
    S1 --> S2["Step 2: test"]
    S2 --> S3["Step 3: build image"]
    S3 --> AR["Artifact Registry"]
    S3 --> DEP["Deploy to Cloud Run, GKE or others"]
    CB --> LOG["Cloud Logging and build history"]
    CB --> PUB["Pub/Sub status messages"]
    

The control side and the work side

It helps to picture Cloud Build in two halves. The control side is the managed service that accepts requests, checks permissions, queues builds, tracks status, and keeps history. The work side is the pool of virtual machines that actually run the steps. You never log in to either half. You only talk to the service through the console, the command-line tool, or the programming interface.

How the steps share a machine

All steps in one build run one after another on the same machine by default. Every step is its own container, but they all see the same shared workspace folder. The first step might download code into that folder, the second might run tests on it, and the third might package it. When steps are marked as independent, they can run side by side to save time.

Global and regional builds

A build can run in a chosen region or be handled by the service globally. A regional build keeps the processing and the logs in the place you pick, which helps when company or legal rules say where data must stay, and it keeps delays low when the registry and deployment targets are nearby. A global build is simpler to set up, because you do not have to decide on a place. When you have no strict rule, choose the region nearest to your artifacts and keep everything consistent, since mixing many regions makes pipelines harder to understand and can add data transfer charges.

The role of the command-line tool and the console

You can work with Cloud Build in three ways. The console is the web page where you create triggers, read logs, and look at history. The command-line tool lets you start builds from a terminal or from a script, which is useful for quick experiments and for other automation. The programming interface lets your own software start and watch builds. All three talk to the same service, so a build started in one way appears in the history of the others.

Let us follow a single build from the moment it is requested to the moment its machine disappears.

sequenceDiagram
    participant U as You or a Trigger
    participant API as Cloud Build API
    participant Q as Scheduler
    participant W as Worker Machine
    participant R as Registry or Storage
    participant L as Logs
    U->>API: Request a build with a recipe
    API->>API: Check permissions and validate the recipe
    API->>Q: Queue the build
    Q->>W: Assign a fresh machine
    W->>W: Download source into the workspace
    W->>W: Run steps one by one in containers
    W->>L: Stream log lines
    W->>R: Push images and artifacts
    W-->>API: Report final status
    API-->>U: Success, failure or timeout
    

The stages in plain words

Statuses you will see

The build configuration is the recipe card. Understanding its parts lets you read any Cloud Build pipeline.

The file is usually named cloudbuild.yaml and kept in the same repository as the code, so the recipe is versioned together with the program. That is a powerful habit: when you go back to an old version of the code, you also get the old recipe that built it.

The main sections

What one step can say

Reading a recipe in your head

A simple recipe for a web application might say, in words: first, run the test tool in a language container; second, build a container image from the project’s instructions file; third, push the image to Artifact Registry; fourth, tell Cloud Run to use the new image. The “images” section lists the image name so that Cloud Build also records it as an official output of the build.

Because every step is a container, a builder is simply a container that happens to hold a useful tool.

Ways to build container images

Choosing builders wisely

• Pin versions. Use a specific version tag, or better a digest, for each builder so that a surprise update does not change your build overnight.
• Prefer small images. Smaller builders download faster, saving seconds on every step of every build.
• Trust carefully. A builder runs with the build’s permissions. A malicious builder could read secrets or tamper with output. Prefer images from sources you trust and consider keeping approved copies in your own registry.
• Keep one tool per step. A step that does one clear thing is easier to debug and cache.

Triggers are what turn Cloud Build from a tool you run into a system that runs by itself.

A trigger says: “When this event occurs in this repository, start a build with this recipe.” You can create as many triggers as you like, each with its own rules and recipe.

Kinds of events

flowchart TD
    E["Something happens in the repository"] --> M{"Does it match a trigger?"}
    M -->|"No"| N["Nothing starts"]
    M -->|"Yes"| F{"Do changed files match the include and ignore filters?"}
    F -->|"No"| N
    F -->|"Yes"| A{"Is approval required?"}
    A -->|"Yes"| P["Wait for a person to approve"]
    A -->|"No"| B["Start the build"]
    P -->|"Approved"| B
    P -->|"Rejected"| N
    

Useful trigger settings

• Branch and tag patterns: Match names such as “main” or anything beginning with “release”. These patterns are called regular expressions.
• Included and ignored files: Start a build only if certain folders changed, or skip it when only documents changed. This is vital in repositories that hold many projects.
• Substitutions: Give each trigger its own values, so one recipe can serve test and production.
• Service account: Choose which identity the triggered build uses.
• Approval: Ask a person to approve before important builds, such as production releases.
• Comment control: For pull requests from outside contributors, require a trusted reviewer to approve the build first, so a stranger cannot run code with your build’s permissions.

Connecting source code

Cloud Build can connect to repositories on popular hosts such as GitHub, GitLab, and Bitbucket, as well as Google’s own hosting option. The connection is made once, with an app or token that you authorize, and after that triggers can watch the repositories you choose. The exact connection methods have changed over the years, and newer connection styles exist alongside older ones, so follow the current documentation when you set this up.

Manual, scheduled, and approved builds

Not every build is caused by code. Sometimes a person wants to press a button, for example to release a version at an agreed time. Sometimes a build should run every night, such as a full rebuild without any caches, a security scan of the latest dependencies, or a data task. For schedules, you pair a timer service with a trigger so that a message or a web call starts the build at the chosen moment. For sensitive builds, you can mark a trigger as needing approval: the build is created but waits, and only someone with the right permission can release it to run. This gives a simple human checkpoint before production changes, and the approver and time are recorded in the history.

A good recipe is flexible and safe. Substitutions make it flexible, and secrets handling makes it safe.

Substitutions: fill-in-the-blank values

A substitution is a placeholder whose name begins with a dollar sign. When a build runs, Cloud Build replaces each placeholder with its real value. This lets a single recipe be used for different branches, projects, and environments.

Custom substitution names conventionally start with an underscore, which keeps them separate from the built-in ones. A very common habit is to tag each image with the short commit identifier, so you can always tell exactly which code produced a given image.

Secrets: keep passwords out of the recipe

A recipe is stored in a repository that many people can read. Never write passwords, keys, or tokens in it. Instead:

• Store the secret in Secret Manager, Google Cloud’s safe for sensitive values.
• In the recipe, list which secrets exist and give them short names.
• In only those steps that truly need a secret, expose it as an environment variable that exists just for that step.
• Give the build’s service account permission to read just those secrets.

Cloud Build also hides known secret values in its logs, but you should not rely on that alone. Never print a secret on purpose.

Since build machines are thrown away, you must save the results deliberately, and you can also save time by remembering earlier work.

Where results go

Images versus artifacts

The “images” section of the recipe is for container images, which are pushed to a registry only if the whole build succeeds. The “artifacts” section is for other files, which are copied to Cloud Storage. Using these sections, rather than a manual push inside a step, lets Cloud Build record the outputs as official results of the build, which is useful for tracking and for security records.

Tagging images sensibly

• Tag with the commit identifier, so every image traces back to one exact change.
• Add a human-friendly tag, such as a version number, for releases.
• Avoid depending on a moving tag like “latest” in production. Deploy by digest or by a fixed tag.

Caching: not repeating work

Because each build starts clean, it may re-download the same libraries and re-create the same image layers every time. Caching remembers earlier results to skip repeated work.

Keeping the registry tidy

Every build that makes an image adds one more item to the registry. After a year of frequent builds there may be tens of thousands. Most are never used again, yet they cost storage money and make it harder to find the right one. Set cleanup rules that keep recent images and all images currently deployed, and delete the rest after a sensible period. Make sure the rule never removes an image that production still runs, because a server that restarts needs to pull it again.

Digests: the exact fingerprint

A tag is a label that can be moved from one image to another. A digest is a long fingerprint calculated from the image contents, so it points to exactly one image forever. Deploying by digest guarantees you run precisely what was tested. Many teams use human-friendly tags for convenience and digests in the final deployment, giving them both readability and certainty.

A slow pipeline makes people wait, and waiting people stop trusting automation. Speed is worth real effort.

flowchart TD
    START["Fetch source"] --> LINT["Style checks"]
    START --> UNIT["Unit tests"]
    START --> SCAN["Dependency scan"]
    LINT --> IMG["Build image"]
    UNIT --> IMG
    SCAN --> IMG
    IMG --> PUSH["Push to registry"]
    PUSH --> DEPLOY["Deploy"]
    

Main speed levers

The trade-off: time versus money

Builds are billed by the minute for the machine type used, so a bigger machine costs more per minute. But if it finishes in a quarter of the time, the total can be similar or lower, and developers get answers sooner. The way to find out is to measure: try the same build on two sizes and compare time and cost. Remember that some steps cannot use many cores, so a bigger machine is not always faster.

Measure first

• Look at the build timeline in the console to see which step takes longest.
• Attack the longest step first. Improving a ten-second step does little for a ten-minute build.
• Record build duration over time, so you notice when a change quietly makes things slower.

Where a build runs matters for speed, security, and what the build can reach.

flowchart TD
    Q{"What does the build need?"} --> A{"Must it reach private systems, such as an internal database or a private network?"}
    A -->|"No"| B{"Need fixed machine sizes or stronger isolation?"}
    A -->|"Yes"| PRIV["Use a private pool connected to your network"]
    B -->|"No"| DEF["Use the default pool"]
    B -->|"Yes"| PRIV
    DEF --> D1["Shared, managed by Google, quick to start"]
    PRIV --> P1["Dedicated to your project, you choose machine type and network"]
    

The default pool

The default pool is a shared fleet of machines run by Google. It needs no setup, starts quickly, and offers a range of machine sizes. Builds in it reach the public internet and Google Cloud services, but they cannot directly reach resources inside your private network. For most small and medium projects, this is the right place to start.

Private pools

A private pool is a set of build machines dedicated to your project. You decide the region, machine type, and disk size. Most importantly, a private pool can be connected to your own virtual private cloud network, the private network you build inside Google Cloud, so builds can reach internal systems such as a private database, an internal package server, or a code host that is not on the public internet. You can also restrict outbound internet access from the pool.

Choosing regions

Builds can be started globally or in a specific region. Regional builds help meet rules about where data may be processed, and can reduce delay when your code, registry, and deployment targets are in the same area. Match the build region to where you keep your artifacts.

Building an image is only half the story. The real goal is getting the new version safely in front of users.

sequenceDiagram
    participant Dev as Developer
    participant Repo as Repository
    participant CB as Cloud Build
    participant AR as Artifact Registry
    participant CD as Cloud Deploy
    participant Stage as Staging
    participant Prod as Production
    Dev->>Repo: Merge a change
    Repo->>CB: Trigger fires
    CB->>CB: Test and build image
    CB->>AR: Push tagged image
    CB->>CD: Create a release
    CD->>Stage: Roll out to staging
    Stage-->>CD: Checks pass
    CD->>Prod: Promote after approval
    

Where builds can deploy

Cloud Build or Cloud Deploy?

Cloud Build is excellent at running tasks, including a deploy command. Cloud Deploy is a separate service designed for the release process itself: moving the same artifact through a series of environments, with approvals, history, and rollback. Many teams use both: Cloud Build makes and tests the image, then hands a release to Cloud Deploy. Small projects can simply deploy straight from Cloud Build.

Release strategies

A typical deployment to Cloud Run, in words

Because Cloud Run keeps earlier revisions, going back is usually just a change of where traffic points, which is why serverless platforms make rollbacks so pleasant.

A build system holds the keys to your production environment. If an attacker controls the build, they control what your users run.

That is why build security has become one of the hottest topics in software. The set of everything that touches your software on its way to users, from source code to dependencies to build tools to registries, is called the software supply chain. Securing it means making sure each link is trusted and tamper-evident.

A chain you can trust

Roles in plain words

Permissions in Google Cloud are grouped into roles. A build usually needs a small, predictable set of them. Think of it as a list of doors the build is allowed to open.

Grant each permission on the smallest thing possible, such as one repository or one secret, instead of the whole project. Review these permissions regularly, since pipelines change and old permissions are rarely removed unless someone checks.

A pipeline that fails silently is worse than no pipeline. Make results visible to the right people at the right time.

Logs

Every build streams its output line by line. You can read it in the console while the build runs and afterward. Depending on the logging option you choose, logs are written to Cloud Logging, to a Cloud Storage bucket, to both, or in some cases not at all. When a build uses a user-specified service account, you must choose a logging option explicitly. Logs are the first place to look when a step fails.

Build history

The console keeps a list of past builds with status, duration, trigger, commit, and the timeline of each step. This makes it simple to answer questions such as “what changed between the last good build and the first bad one?”

Notifications

What to measure

The last two, together with lead time from commit to production and the time to recover from a failure, are often called the four key delivery measures, widely used by teams to judge how well their delivery works.

Reading a failed build

When a build fails, a calm routine saves a lot of time. First look at which step failed in the timeline, then open that step’s log and find the first error line. Next, ask what changed since the last successful build: the code, the recipe, a builder version, a secret, or a permission. Finally, try to reproduce the failure in the same builder image. Writing down the cause and the fix in a short team note turns each failure into shared knowledge.

Cloud Build bills for the time your builds use machines. A little understanding keeps the bill small and predictable.

How charges usually work

• Build minutes: You are charged for the minutes that builds run, at a rate that depends on the machine type. Bigger machines cost more per minute.
• Free allowance: There is typically a monthly allowance of free build minutes on a standard machine type. The size of that allowance and which machine types it applies to have changed in the past, so check the pricing page.
• Private pools: Priced differently from the default pool, usually based on the machines in use.
• Other services: Storage for images and artifacts, logs, network transfer, and the services you deploy to all have their own prices.

Ways to keep costs down

Quotas and limits

Cloud Build has limits, such as how many builds may run at the same time in a region, how many triggers you may create, and how large the source or logs may be. Extra builds wait in a queue. Limits and defaults change, so look at the quotas page in the console, set alerts as you approach them, and request increases before big launches.

No tool is right for everyone. An honest comparison helps you decide when Cloud Build fits.

Key trade-offs

Alternatives to consider

• GitHub Actions is built into GitHub, with a huge library of shared actions. It is a natural choice for projects that live on GitHub, and it can still deploy to Google Cloud.
• GitLab CI is built into GitLab and covers the whole development lifecycle there.
• Jenkins is a long-established, self-hosted automation server with endless plugins, at the price of running and maintaining it.
• CircleCI and similar hosted services provide polished hosted pipelines across many platforms.
• AWS CodeBuild and Azure Pipelines are the equivalents on other major clouds.
• Tekton and Argo Workflows are open-source, Kubernetes-based pipeline engines for teams who want to run pipelines inside their own clusters.

Many organizations mix tools. A common pattern is to use the code host’s pipelines for tests and Cloud Build for the Google Cloud specific steps of building and deploying.

Teams who run pipelines for years end up repeating the same good ideas, and avoiding the same bad ones.

Patterns that work

Anti-patterns to avoid

A checklist of good habits, a list of beginner mistakes, and a map of what to try when builds misbehave.

Best practices

• Keep the build configuration in the same repository as the code, and review changes to it.
• Give every step a clear id and a single purpose.
• Pin builder versions and base images, and update them on purpose with tests.
• Use dedicated, minimal service accounts and Secret Manager for every secret.
• Run fast checks first and independent steps in parallel.
• Cache layers and dependencies, but run an uncached build regularly.
• Tag images with commit identifiers and deploy immutable versions.
• Set timeouts for steps and for the whole build.
• Use file filters on triggers to avoid pointless builds.
• Send failures of important branches to the people who can fix them.
• Record provenance and consider enforcing it at deployment.
• Set budget alerts and clean up old artifacts.

Common beginner mistakes

Troubleshooting guide

Automation is only as good as the checks it runs. A pipeline should make bad changes hard to ship and bad releases easy to undo.

Layers of checks

Put fast checks early so most failures are found within a minute or two. Run the slow checks later or in separate pipelines, so everyday feedback stays quick.

Quality gates

A quality gate is a rule that must be satisfied before the pipeline continues. Examples: all tests pass, no serious vulnerabilities, code coverage does not fall below an agreed level, a person approves, or the new version stays healthy during a canary phase.

stateDiagram-v2
    [*] --> Building
    Building --> Testing: image built
    Testing --> Staging: all checks pass
    Testing --> Rejected: a check fails
    Staging --> AwaitingApproval: staging healthy
    AwaitingApproval --> Production: approved
    AwaitingApproval --> Rejected: declined
    Production --> Monitoring: released
    Monitoring --> Stable: no problems
    Monitoring --> RolledBack: errors detected
    RolledBack --> [*]
    Stable --> [*]
    Rejected --> [*]
    

Rollback: the undo button

Even with excellent testing, some problems only show in real use. Plan for this from the start.

• Keep previous images in the registry so you can redeploy an earlier, known-good version quickly.
• Deploy by immutable tag or digest, so “go back” has an exact target.
• Use gradual release strategies, such as canary, to limit how many users see a bad version.
• Be careful with database changes. Make them backward compatible, so the old version still works if you roll back.
• Practice rollbacks before you need them.

Flaky tests: the trust killer

A flaky test is a test that sometimes passes and sometimes fails on the same code, usually because of timing, shared data, or a dependence on an outside service. Flaky tests are poisonous for automation. After a few false alarms people start pressing “run again” without thinking, and eventually they ignore real failures too. Track which tests fail unpredictably, fix the cause, or move them aside until they are repaired. A smaller set of tests that everyone trusts is worth more than a large set that everyone doubts.

Test environments

Tests that need a database or another service can start small temporary copies inside the build, for example containers running beside the step, so the test starts from a known state and leaves nothing behind. This keeps tests independent and avoids the common trouble of several builds sharing one test database and disturbing each other.

These illustrative situations show how the ideas combine. They are examples to learn from, not claims about any real company.

An example decision record

Short answers to the questions people ask most.

You began with the idea of an automatic robot baker and ended with secure, fast, well-monitored delivery pipelines. Here is the journey in a few lines.

Cloud Build is Google Cloud’s serverless CI/CD engine. A recipe file lists steps, each run in a container on a fresh machine that disappears afterward. Triggers start builds automatically when code changes. Images and files must be saved deliberately to Artifact Registry or Cloud Storage. Substitutions make recipes reusable, and Secret Manager keeps sensitive values out of them. Parallel steps, caching, and the right machine size make builds fast, while private pools let builds reach internal networks. Cloud Deploy and release strategies carry the result safely to users, and monitoring, quality gates, and rollbacks protect them when something goes wrong. Throughout, narrow permissions, pinned tools, and signed provenance protect the software supply chain.

Because defaults, limits, free allowances, prices, and connection methods change from time to time, confirm the current details in the official Google Cloud documentation before you finalize your design.