How to Use cloudbuild.yaml in GCP for Automated Builds

Use cloudbuild.yaml in GCP to define build steps for Cloud Build. This file lists commands and actions to run in sequence, automating tasks like compiling code or deploying apps. Upload it to Cloud Build to start automated builds.

Syntax

The cloudbuild.yaml file defines a list of build steps that Cloud Build executes in order. Each step specifies a Docker image and commands to run inside that image. You can also define environment variables, artifacts to store, and timeout settings.

• steps: List of build steps.
• name: Docker image to use for the step.
• args: Commands or arguments to run inside the container.
• timeout: Optional max time for the build.
• artifacts: Files to save after build.

yaml

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args: ['version']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
artifacts:
  objects:
    location: 'gs://my-bucket/build-artifacts/'
    paths: ['**']
timeout: '1200s'

Example

This example shows a simple cloudbuild.yaml that prints the gcloud version, builds a Docker image, and pushes it to Google Container Registry. It demonstrates how to chain steps and use official Cloud Build builder images.

yaml

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args: ['version']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'gcr.io/my-project/my-image']

Output

Starting Step #0
Step #0: gcloud version output
Starting Step #1
Step #1: Docker build output
Starting Step #2
Step #2: Docker push output
Build completed successfully

Common Pitfalls

Common mistakes include:

• Using incorrect Docker image names in name.
• Forgetting to specify args as a list of strings.
• Not setting permissions for Cloud Build to access required resources.
• Ignoring build timeouts causing unexpected failures.

Always validate your YAML syntax and test builds with small steps first.

yaml

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: 'build -t gcr.io/my-project/my-image .'

# Wrong: args should be a list, not a single string

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project/my-image', '.']

# Correct: args as list of strings

Quick Reference

Field	Description
steps	List of build steps to run in order
name	Docker image used for each step
args	Commands or arguments run inside the step container
timeout	Maximum time allowed for the build (e.g., '1200s')
artifacts	Files or directories to save after build
images	Docker images to push after build completes

Key Takeaways

Define build steps in cloudbuild.yaml using Docker images and commands.

Use lists for args and specify official Cloud Build builder images.

Test your cloudbuild.yaml with simple steps before complex builds.

Set proper permissions and timeouts to avoid build failures.

Use artifacts and images fields to save outputs and push images.