Using community-contributed builders and custom builders

This page explains how to use community-contributed builders and custom builders in Cloud Build. The Cloud Build developer community provides open-source builders that you can use to execute your tasks. If the task you want to perform requires capabilities that are not provided by an existing image, you can build your own custom image and use it in a build step. To learn about the different types of builders, see Cloud Builders.

If you're new to Cloud Build, read the quickstarts and the Build configuration overview first.

Using community-contributed builders

Pre-built images are not available for community-contributed builders; to use these builders in a Cloud Build config file, you must first build the image and push it to Container Registry in your project.

To use a community-contributed builder:

  1. Build and push the builder:

    1. Navigate to your project root directory.

    2. Clone the cloud-builders-community repository:

      git clone https://github.com/GoogleCloudPlatform/cloud-builders-community.git

    3. Navigate to the builder image you want to use, where builder-name is the directory that contains the builder:

      cd cloud-builders-community/builder-name

    4. Submit the builder to your project:

      gcloud builds submit .

    5. Navigate back to your project root directory:

      cd ../..

    6. Remove the repository from your root directory:

      rm -rf cloud-builders-community/

  2. In your Cloud Build config file, use the builder in a build step:

    YAML 

    steps:
- name: 'gcr.io/project-id/builder-name'
  args: ['arg1', 'arg2', ...]
...

    JSON 

    {
  "steps": [
  {
    "name": "gcr.io/project-id/builder-name",
    "args": [
      "arg1",
      "arg2",
      ...
    ]
    ...
  }
  ]
}

  3. Use the build config file to start the build manually or build using triggers.

For examples on using community-contributed builders, see Deploy to Firebase and Build VM images using Packer.

Creating a custom builder

If the task you want to perform requires capabilities that are not provided by a public image, a supported builder, or a community-contributed builder, you can build your own image and use it in a build step.

Some examples of when you might want to use a custom builder image are:

  • Downloading source code or packages from external locations.
  • Using an external tool chain.
  • Caching any necessary libraries.
  • Pre-building source (with Cloud Build responsible only for potentially packaging the build into an image).

Like any other builder, a custom builder runs with the source mounted under /workspace, and is run with a working directory in /workspace. Any files left in /workspace by a given build step are available to other build steps.

Your custom builder can push to or pull from a repository in Container Registry (hosted at gcr.io/$PROJECT-NAME/) to which your build service account has access.

The following steps show how to create and use a custom builder with an example Dockerfile:

  1. Create a custom builder image:

    1. Create the Dockerfile for the custom builder. The following code shows an example Dockerfile:

        FROM alpine
  RUN apk add curl
  CMD curl https://httpbin.org/ip -s > myip.txt; echo "*** My IP is: $(cat myip.txt)"

    2. Build and push the custom builder to the Container Registry in your project, replacing values for project-id and image-name:

        gcloud builds submit --tag gcr.io/project-id/image-name

  2. Use the custom builder image in Cloud Build by specifying the builder in the name field of a build step:

    YAML 

        steps:
    - name: 'gcr.io/project-id/image-name'
      id: Determine IP of this build worker

    JSON 

        {
      "steps": [
      {
        "name": "gcr.io/project-id/image-name",
        "id": "Determine IP of this build worker"
      }
      ]
    }

  3. Use the build config file to start the build manually or build using triggers.

What's next