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

Prebuilt 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 Artifact 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 Artifact 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 Artifact 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

• Learn how to run bash scripts in build steps .
• Learn how to configure build step order .
• Learn how to write a basic build config file .