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 buider, 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 Cloud Build service account has access.

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

  1. Create a Docker 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 image in a build step in your build config file:

    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