Building and debugging locally

This page explains how to use Cloud Build on your local machine. Using the local builder, you can:

Iterate builds more quickly on your local machine.
Use a dry run to lint your config file.

Before you begin

Install and initialize the Google Cloud SDK.
Install Docker. It's a best practice to use the same Docker version as Cloud Build.
You need source code to build, a build config file for your build, and access from your local machine to any tools and dependencies required by your build steps.
If your build needs access to a private registry, install and configure the Docker credential helper for Cloud Build by running the commands:
```
gcloud components install docker-credential-gcr
gcloud auth configure-docker
```

Install the local builder

The local builder is a component of the Google Cloud SDK's gcloud tool. You can install it using the gcloud command, apt-get, or yum, depending on your system.

To install the local builder, run the following command:

gcloud

gcloud components install cloud-build-local

apt-get

sudo apt-get install google-cloud-sdk-cloud-build-local

yum

sudo yum install google-cloud-sdk-cloud-build-local

After the local builder is installed, to view:

The command line help, run the command:
```
cloud-build-local --help
```
The installed version of the local builder, run the command:
```
cloud-build-local --version
```

Build locally

Warning: Run one build at a time on your local machine. Running multiple builds in parallel will cause the local builder to fail.

If you don't already have a project set up, you can test the local builder using the config from the Quickstart.

To build locally, run the following command:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

Where:

[BUILD_CONFIG] is the path to and the name of your config file.
- For example, if your config file is in the working directory and named cloudbuild.json, use the flag --config=cloudbuild.json.
- The default value is cloudbuild.yaml, so if your config file is in the working directory and named cloudbuild.yaml, you do not need to add this flag.
[SOURCE_CODE] is the path to your source code.
- As with Cloud Build, you can use . for the source if the source code is in your current working directory.
- If your build does not need source code, use the flag --no-source in place of [SOURCE_CODE].
--dryrun=false allows your build to run. The flag --dryrun is true by default. Running with the default value lints your config file but does not run build commands. You need to explicitly set --dryrun=false to execute your build.
--push pushes the resulting images or artifacts to the destination that's defined by the field images or artifacts in the config file. By default, images and artifacts are built but are not pushed.

After the build is complete, the images created are available on your local machine through Docker. If you added --push to the build command, they are available in the specified repository.

Preserve intermediary artifacts

During a build, intermediary artifacts are placed in a directory called workspace. By default, the builder deletes the workspace and its contents at the end of a build.

To run a build and to preserve the artifacts from the workspace, run the command:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

Where:

[BUILD_CONFIG] is the path to your config file,
[SOURCE_CODE] is the path to your source code, and
[LOCAL_DIRECTORY_PATH] is the local directory where you want the workspace to be stored on your local machine. This directory must not reside within the [SOURCE_CODE] directory.

Preserving the workspace allows you to:

Analyze intermediary artifacts when debugging a build.
Access a build result, such as a binary, that the builder created in the workspace.

Use substitutions in your build

To use substitutions in your build, use the flag --substitutions along with the key=value pair that you want to substitute. Note that you can specify values for certain default variables as well as variables that you have defined.

For example,

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

Where:

[BUILD_CONFIG] is the path to your config file,
[SOURCE_CODE] is the path to your source code, and
In this example, _KEY will be substituted with value, and _FOO will be substituted with foo.

For details about substitutions, including required syntax, see Substitutions.

Debug your build locally

To debug your build, you can:

Verify that the config file is correct by doing a dry run of the build.
Inspect the intermediary artifacts created in the workspace during the build. To do so, see Preserve the intermediary artifacts above.

Local builds run with the permissions available at execution time on your local host. In Cloud Build, the build step executes with the permissions of your project's service account. If you are debugging a permissions issue, be sure to set up your permissions to match those of the Cloud Build service account so that the local builds are in an environment as close as possible to the Cloud Build environment.

Verify the build with a dry run

A dry run of the build will lint the config file, and will produce errors if it detects any issues. A dry run does not execute the build, so you can verify the config file without the overhead of running the build. Using the local builder is the only way to do a dry run of a build.

Do a dry run of the build by using the command:
```
cloud-build-local --config=[BUILD_CONFIG] [SOURCE_CODE]
```
Where:
- [BUILD_CONFIG] is the path to your config file,
- [SOURCE_CODE] is the path to your source code.
Review any error messages and fix any issues in your config file.

Restrictions and limitations

The local builder can build on only Linux or macOS.
The local builder runs one build at a time on a given host. Running multiple builds in parallel will cause the local builder to fail.

Differences between the local builder and Cloud Build

The local builder is designed to mimic Cloud Build. A build that runs successfully on the local builder should run with the same behavior on Cloud Build.

Differences that do exist between the two builders include:

The local builder executes on your local machine, Cloud Build executes on Google Cloud Platform.
To run the build, the local builder uses your personal account, and the Cloud Build uses the cloudbuild service account [PROJECT_ID]@cloudbuild.gserviceaccount.com. If you set any permissions on your personal account for the local builder, you may need to replicate these permissions on the cloudbuild service account. For details, see Setting Service Account Permissions.
The version of Docker used by the builders could be different. During execution, the local builder prints a warning whenever the Docker version installed is different from the one used in Cloud Build. It's a best practice to use the same Docker version as the one used by Cloud Build.

What's next?

Learn about building with Cloud Build.