Overview of Container Builder

Google Cloud Container Builder is a tool that executes your container image builds on Google Cloud Platform's infrastructure in a fast, reliable, and consistent way.

Container Builder can import source code from a variety of repositories or cloud storage spaces, execute a build to your specifications, and produce artifacts such as Docker containers or Java archives.

Components of Container Builder

The following sections describe the components that make up Container Builder.


Container Builder uses Docker to execute builds and, optionally, to create Docker containers.

A containerized application, or container, is an application packaged into hardware-independent, isolated user-space instances.

Build requests and build steps

A build request configuration file is a YAML or JSON document which tells Container Builder how to execute your build.

Build requests are made up of build steps, which are containers that are executed as part of your build. Calling build steps is analogous to calling commands in a script. You can create your own build steps for use in your builds.

You can also use standard Docker Hub images in Container Builder, such as Ubuntu and Gradle.

Supported build steps

The Container Builder team maintains a set of supported, open-source build steps on GitHub. Pre-built images of these build steps are hosted at:


Build triggers

Container Builder's build triggers feature enables you to create an automated continuous integration/continuous delivery (CI/CD) workflow that starts new builds when your source code changes.

You can integrate build triggers with many code repositories, including Cloud Source Repository, GitHub, and Bitbucket.

Build history

The build history menu displays details and logs for every build Container Builder executes.

How builds work

The following steps describe, in general, the lifecycle of a Container Builder build:

  1. Prepare your application code, any needed assets, and a Dockerfile.
  2. Create a build request file in YAML or JSON format, which contains instructions for Container Builder.
  3. Submit the build to Container Builder.
  4. Container Builder executes your build based on the build request you provided.
  5. If applicable, any built images are pushed to Container Registry.

Container Builder interfaces

You can use Container Builder with the gcloud command-line tool or Container Builder's REST API.

Using the gcloud command-line tool

You can submit build requests to Container Builder by using the gcloud command-line tool.

The following command submits a build to Container Builder:

gcloud container builds submit

For more information about gcloud, see Quickstart with the gcloud command-line tool.

Using the Container Builder API

You can request builds using the Container Builder REST API.

As with other Cloud Platform APIs, you must authorize access using OAuth2. After you have authorized access, you can then use the API to start new builds, view build status and details, list builds per project, and cancel builds that are currently in process.

For more information, see the API documentation.

Running builds locally

If you want to test your build before submitting it to Container Builder, you can run your build locally using the container-builder-local tool.


To use container-builder-local, ensure that you meet the following prerequisites:

  • You have installed the gcloud command-line tool, which is included in the Cloud SDK
  • You have installed Docker and the docker command-line tool
  • You have access to any tools and dependencies required by your build steps

Additionally, if your build needs access to a private registry in Container Builder, you must install and configure the Docker credential helper for Container Builder.

To install the credential helper, run the following command:

gcloud components install docker-credential-gcr

Before using the tool, you need to set your project as active. To do this, run the following command:

gcloud config set project [PROJECT-ID]


To install container-builder-local, run the following command:

gcloud components install container-builder-local

Using the local builder

To use the tool, run the following command, where --config specifies the build request file:

container-builder-local --config=[BUILD-REQUEST] [SOURCE-CODE]

For example, the following command uses config.yaml and looks for the source code in the present working directory:

container-builder-local --config=config.yaml .

By default, container-builder-local lints your config file and prints the output of the build but does not run the commands. To disable this behavior and run the build, specify the --dryrun=false option.

Similarly, the tool does not push images created during the build to an image registry, such as Container Registry. To push images, specify the --push option.

You can use the --substitutions option to pass in substitutions for variables specified in the build request. For example, the following command passes in two substitutions:

container-builder-local --substitutions=_FOO=bar,_APPLE=orange --config=config.yaml .

Local builds run with the permissions available at execution time on your local host. In Container Builder, your 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 Container Builder service account to run in an environment as close as possible to the Container Builder environment.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Container Builder