Creating a Basic Build Configuration File

This page describes how to create a build configuration file that you can use to start a build on Cloud Build.

A build config file defines the fields that are needed for Cloud Build to perform your tasks. You'll need a build config file if you're starting builds using the gcloud command-line tool or build triggers. You can write the build config file using the YAML or the JSON syntax.

Before you begin

Creating a build config

The following steps explain how to create a simple build config file. Each of the fields in the config file defines a part of the task you want to perform. The only required field in the build config file is the name field for a step; all other fields are optional.

YAML

  1. Create the build config file. In your project root directory, create a file named cloudbuild.yaml. This is your Cloud Build build config file.

  2. Add the steps field. The steps section in the build config file contains the build steps that you want Cloud Build to perform.

    steps:
    
  3. Add the first step. Under steps:, add a name field and point it to a container image to execute your task. Cloud Build and its developer community provides several container images with common tools and languages installed in them. You can use any of these images (also called Cloud Builders), or any publicly available image in a build step. For information on different types of container images you can use in a build step, see Cloud Builders.

    The following snippet shows a build step with a docker builder gcr.io/cloud-builders/docker, which is a container image running Docker.

    steps:
    - name: 'gcr.io/cloud-builders/docker'
    
  4. Add step arguments. The args field of a step takes a list of arguments and passes them to the builder referenced by the name field.

    The following example takes the arguments for calling the docker build command and passes them to the docker builder. The arguments include:

    • the command name (build)
    • Docker tag (t)
    • the name of the image to be built (gcr.io/my-project/my-image)
    • the location of the source code (., meaning that the source code is present at the current working directory).

      steps:
      - name: 'gcr.io/cloud-builders/docker'
        args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
      
  5. Include any additional fields for the step. You can add more fields to your build step such as environment variables and working directories, to configure your build steps. For a description of all the fields you can include in a build step, see Build steps.

    In the following example, the timeout field is included to specify that the docker step must be timed-out after 500s:

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
      timeout: 500s
    
  6. Add more steps. You can add any number of build steps to your build config file by including additional name fields and pointing them to cloud builders.

    The following snippet includes two more steps to the build config file:

    • a docker build step to invoke the docker push command, to push the image build in the previous step to Container Registry.
    • a kubectl build step to invoke the kubectl set image command, which deploys the image to a Kubernetes Engine cluster. The env field is included to specify the Compute Engine zone and Kubernetes Engine cluster.

      steps:
      - name: 'gcr.io/cloud-builders/docker'
        args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
        timeout: 500s
      - name: 'gcr.io/cloud-builders/docker'
        args: ['push', 'gcr.io/my-project/my-image']
      - name: 'gcr.io/cloud-builders/kubectl'
        args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
        env:
        - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
        - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
      
  7. Include additional build configuration. You can configure the build further by including fields such as machineType and tags. For the complete list of fields you can include in the build config file see Build Configuration Overview.

    The following example adds the following fields for the build:

    • machineType that specifies the virtual machine size to run the build.
    • timeout that specifies the time after which the build will be timed out.
    • tags for annotating the build.

      steps:
      - name: 'gcr.io/cloud-builders/docker'
        args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
        timeout: 500s
      - name: 'gcr.io/cloud-builders/docker'
        args: ['push', 'gcr.io/my-project/my-image']
      - name: 'gcr.io/cloud-builders/kubectl'
        args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
        env:
        - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
        - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
      options:
          machineType: 'N1_HIGHCPU_8'
      timeout: 660s
      tags: ['mytag1', 'mytag2']
      
  8. Store the built images and artifacts. If your build produces any container images, you can choose to store them in Container Registry. You can do this using the images field.

    The following example stores the image built in the docker step to Container Registry:

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: ['build', '-t', 'gcr.io/my-project/my-image', '.']
      timeout: 500s
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/my-project/my-image']
    - name: 'gcr.io/cloud-builders/kubectl'
      args: ['set', 'image', 'deployment/my-deployment', 'my-container=gcr.io/my-project/my-image']
      env:
      - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
      - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
    options:
        machineType: 'N1_HIGHCPU_8'
    timeout: 660s
    tags: ['mytag1', 'mytag2']
    images: ['gcr.io/my-project/myimage']
    

If your build produces any non-container artifacts, you can store them in Cloud Storage using the artifacts field. For instructions on doing this, see Storing Images and Artifacts.

JSON

  1. Create the build config file. In your project root directory, create a file named cloudbuild.json. This is your Cloud Build build config file.

  2. Add the steps field. The steps section in the config file contains the build steps that you want Cloud Build to perform.

    {
        "steps:" [
        {
        }
        ]
    }
    
  3. Add the first step. Under steps:, add a name field and point it to a container image to execute your task. Cloud Build and its developer community provides several container images with common tools and languages installed in them. You can use any of these images (also called Cloud Builders), or any publicly available image in a build step. For information on different types of container images you can use in a build step, see Cloud Builders.

    The following snippet shows a build step with a docker builder gcr.io/cloud-builders/docker, which is a container image running Docker.

    {
        "steps": [
        {
            "name": "gcr.io/cloud-builders/docker"
        }
        ]
    }
    
  4. Add step arguments. The args field of a step takes a list of arguments and passes them to the builder referenced by the name field.

    The following example takes the arguments for calling the docker build command and passes them to the docker builder. The arguments include:

    • the command name (build)
    • Docker tag (t)
    • the name of the image to be built (gcr.io/my-project/my-image)
    • the location of the source code (., meaning that the source code is present at the current working directory).

      {
          "steps": [
          {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                  "build",
                  "-t",
                  "gcr.io/my-project/my-image",
                  "."
              ]
          }
          ]
      }
      
  5. Include any additional fields for the step. You can add more fields to your build step such as environment variables and working directories, to configure your build steps. For a description of all the fields you can include in a build step, see Build steps.

    In the following example, the timeout field is included to specify that the docker step must be timed-out after 500s:

    {
        "steps": [
        {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
                "build",
                "-t",
                "gcr.io/my-project/my-image",
                "."
            ],
            "timeout": "500s"
        }
        ]
    }
    
  6. Add more steps. You can add any number of build steps to your build config file by including additional name fields and pointing them to cloud builders.

    The following snippet includes two more steps to the build config file:

    • a docker build step to invoke the docker push command, to push the image build in the previous step to Container Registry.
    • a kubectl build step to invoke the kubectl set image command, which deploys the image to a Kubernetes Engine cluster. The env field is included to specify the Compute Engine zone and Kubernetes Engine cluster.

      {
          "steps": [
          {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                  "build",
                  "-t",
                  "gcr.io/my-project/my-image",
                  "."
              ],
              "timeout": "500s"
          },
          {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                  "push",
                  "gcr.io/my-project/my-image",
              ],
          },
          {
              "name": "gcr.io/cloud-builders/kubectl",
              "args": [
                  "set",
                  "image",
                  "deployment/my-deployment",
                  "my-container=gcr.io/my-project/my-image"
              ],
              "env": [
                  "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
                  "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
              ]
          }
          ]
      }
      
  7. Include additional build configuration. You can configure the build further by including fields such as machineType and tags. For the complete list of fields you can include in the build config file see Build Configuration Overview.

    The following example adds the following fields for the build:

    • machineType that specifies the virtual machine size to run the build.
    • timeout that specifies the time after which the build will be timed out.
    • tags for annotating the build.

      {
          "steps": [
          {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                  "build",
                  "-t",
                  "gcr.io/my-project/my-image",
                  "."
              ],
              "timeout": "500s"
          },
          {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                  "push",
                  "gcr.io/my-project/my-image",
              ],
          },
          {
              "name": "gcr.io/cloud-builders/kubectl",
              "args": [
                  "set",
                  "image",
                  "deployment/my-deployment",
                  "my-container=gcr.io/my-project/my-image"
              ],
              "env": [
                  "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
                  "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
              ]
          }
          ],
          "options": {
              "machineType": "N1_HIGHCPU_8"
          },
          "timeout": "660s",
          "tags": [
              "mytag1",
              "mytag2"
          ]
      }
      
  8. Store the built images and artifacts. If your build produces any container images, you can choose to store them in Container Registry. You can do this using the images field.

    The following example stores the image built in the docker step to Container Registry:

    {
        "steps": [
        {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
                "build",
                "-t",
                "gcr.io/my-project/my-image",
                "."
            ],
            "timeout": "500s"
        },
        {
                "name": "gcr.io/cloud-builders/docker",
                "args": [
                    "push",
                    "gcr.io/my-project/my-image",
                ],
        },
        {
            "name": "gcr.io/cloud-builders/kubectl",
            "args": [
                "set",
                "image",
                "deployment/my-deployment",
                "my-container=gcr.io/my-project/my-image"
            ],
            "env": [
                "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
                "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
            ]
        }
        ],
        "options": {
            "machineType": "N1_HIGHCPU_8"
        },
        "timeout": "660s",
        "tags": [
            "mytag1",
            "mytag2"
        ],
        "images": [
            "gcr.io/my-project/myimage"
        ]
    }
    

If your build produces any non-container artifacts, you can store them in Cloud Storage using the artifacts field. For instructions on doing this, see Storing Images and Artifacts.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Build