Submit a build via CLI and API

This page describes how to start a build in Cloud Build manually using the Google Cloud CLI and the Cloud Build API.

Before you begin

  • If you want to use the command-line examples in this guide, install the Google Cloud CLI.
  • To build using the Cloud Build build config, create a build config file.
  • To build using a Dockerfile, have your Dockerfile ready.
  • If your build requires source code, have your source code ready.

Required IAM permissions

For instructions on granting IAM roles, see Configure access to Cloud Build resources.

Running builds

You can specify the source of your build using the Build source field. The Build source field is one of the following: storage_source, repo_source, git_source and connected_repository.

Submit builds with storage_source

gcloud

Using a Dockerfile:

Your Dockerfile contains all information needed to build a Docker image using Cloud Build.

To run a build request using your Dockerfile, run the following command from the directory containing your application code, Dockerfile, and any other assets:

gcloud builds submit --region=us-west2 --tag gcr.io/PROJECT_ID/IMAGE_NAME .

Where:

  • PROJECT_ID is the name of your Google Cloud project.
  • IMAGE_NAME is the image to be built.
  • . specifies that the source code is in the current working directory.

The full name of the image to be built is gcr.ioPROJECT_ID/IMAGE_NAME. Images pushed to Container Registry use the registry name format.

The gcloud builds submit command:

  • compresses your application code, Dockerfile, and any other assets in the current directory as indicated by .;
  • uploads the files to a Cloud Storage bucket;
  • initiates a build in the location us-west2 using the uploaded files as input;
  • tags the image using the provided name
  • pushes the built image to Container Registry.

As the build progresses, its output is displayed in your shell or terminal window. When the build is complete, you should see an output similar to the following:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

where $BUILD_ID is your build's unique identifier.

Using the Cloud Build build config file:

To submit a build using the build config, run the following command:

    gcloud builds submit --region=us-west2 --config BUILD_CONFIG SOURCE

Where:

  • BUILD_CONFIG is the path to the build config file.
  • SOURCE is the path or URL source code.

When you run gcloud builds submit for the first time in a Google Cloud project, Cloud Build creates a Cloud Storage bucket named [YOUR_PROJECT_NAME]_cloudbuild in that project. Cloud Build uses this bucket to store any source code that you might use for your builds. Cloud Build does not automatically delete contents in this bucket. To delete objects you're no longer using for builds, you can either set up lifecycle configuration on the bucket or manually delete the objects.

The following command demonstrates how to submit a cloudbuild.yaml build request using source code stored in a Cloud Storage bucket.

    gcloud builds submit --region=us-west2 --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

Where:

  • BUCKET is the name of your bucket in Cloud Storage containing your source code to build.
  • SOURCE is the name of your compressed source code file.

You can use . to specify that the source code is in the current working directory:

    gcloud builds submit --region=us-west2 --config=cloudbuild.yaml .

API

To submit the build request using curl:

  1. Create a file named request.json with the following contents:

    {
    "source": {
        "storageSource": {
            "bucket": "BUCKET",
            "object": "SOURCE.tar.gz"
        }
    },
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/PROJECT_ID/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "gcr.io/PROJECT_ID/IMAGE_NAME"
    ]
}

    Where:

    • BUCKET is the name of your Cloud Storage bucket containing your source code to build.
    • SOURCE is the name of your compressed source code file.
    • IMAGE_NAME is the name of the image to be built.

    In this build request, Cloud Build calls the docker build step with the arguments build -t gcr.io/$PROJECT_ID/IMAGE-NAME ..

    The full name of the image to be built is gcr.io/$PROJECT_ID/IMAGE_NAME.

    Images pushed to Container Registry use the registry name format.

  2. Run the following command where PROJECT_ID is your Google Cloud project ID and REGION is one of the supported regions:

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
    --format='value(credential.access_token)')" \
    https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds

    In this command, curl sends request.json in a POST call to the builds endpoint for the projects.builds.create API method.

    The command displays details about your build in your shell or terminal window. The output is a JSON response and appears similar to the following:

        {
        "name": "operations/build/$PROJECT-ID/NmZhZW...",
        "metadata": {
            "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
            "build": {
                "id": $BUILD-ID,
                "status": "QUEUED",
                "source": {
                    "storageSource": {
                        "bucket": "BUCKET",
                        "object": "SOURCE.tar.gz"
                    }
                },
                "createTime": "2017-05-12T18:58:07.341526Z",
                "steps": [
                {
                    "name": "gcr.io/cloud-builders/docker",
                    "args": [
                        "build",
                        "-t",
                        "gcr.io/PROJECT_ID/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "gcr.io/$PROJECT_ID/IMAGE_NAME"
                ],
                "projectId": $PROJECT-ID,
                "logsBucket": "gs://...",
                "sourceProvenance": {
                    "resolvedStorageSource": {
                        "bucket": "BUCKET",
                        "object": "SOURCE.tar.gz"
                        "generation": "..."
                    }
                },
                "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID"
            }
        }
    }

    The JSON response is modeled using the Operation resource in the Cloud Build API. The metadata field is modeled using the Build resource. The QUEUED status indicates that the build is awaiting execution.

Submit builds with connected_repository

gcloud

To run a build request with build source from a 2nd-gen repository resource, run the following command:

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG --region=us-west2

Where:

  • REPOSITORY is the name of the Google Cloud Build 2nd-gen repository, formatted as projects/*/locations/*/connections/*repositories/*.
  • REVISION is the revision to fetch from the Git repository such as a branch, a tag, a commit SHA, or any Git ref.
  • BUILD_CONFIG is the path to the build config file.

As the build progresses, its output is displayed in your shell or terminal window. When the build is complete, you should see an output similar to the following:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

where $BUILD_ID is your build's unique identifier.

gcloudignore: When including source code for the build, the above command uploads all of the files in the specified directory to Google Cloud Platform to build. If you want to exclude certain files in the directory, you can include a file named .gcloudignore in the top-level upload directory; the files that it specifies will be ignored. If no .gcloudignore file is present in the top-level upload directory, but a .gitignore file is, the gcloud CLI will generate a Git-compatible .gcloudignore file that respects your .gitignore-ed files. For more information, see the gcloudignore documentation.

If you do not have source code to pass in to your build, use the --no-source flag where BUILD_CONFIG is the path to the build config file:

    gcloud builds submit --region=us-west2 --config=BUILD_CONFIG --no-source

API

To submit the build request using curl:

  1. Create a file named request.json with the following contents:

    {
    "source": {
        "connectedRepository": {
            "repository": "REPOSITORY",
            "revision": "REVISION"
        }
    },
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/PROJECT_ID/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "gcr.io/PROJECT_ID/IMAGE_NAME"
    ]
}

    Where:

    • REPOSITORY is the name of the Google Cloud Build 2nd-gen repository, formatted as projects/*/locations/*/connections/*repositories/*.
    • REVISION is the revision to fetch from the Git repository such as a branch, a tag, a commit SHA, or any Git ref.
    • IMAGE_NAME is the name of the image to be built.

    In this build request, Cloud Build calls the docker build step with the arguments build -t gcr.io/PROJECT_ID/IMAGE_NAME ..

    The full name of the image to be built is gcr.io/PROJECT_ID/IMAGE_NAME. Images pushed to Container Registry use the registry name format.

  2. Run the following command where PROJECT_ID is your Google Cloud project ID and REGION is one of the supported regions:

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
    --format='value(credential.access_token)')" \
    https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds

    In this command, curl sends request.json in a POST call to the builds endpoint for the projects.builds.create API method.

    The command displays details about your build in your shell or terminal window. The output is a JSON response and appears similar to the following:

        {
        "name": "operations/build/$PROJECT-ID/NmZhZW...",
        "metadata": {
            "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
            "build": {
                "id": $BUILD-ID,
                "status": "QUEUED",
                "source": {
                    "connectedRepository": {
                        "repository": "REPOSITORY",
                        "revision": "REVISION"
                    }
                },
                "createTime": "2017-05-12T18:58:07.341526Z",
                "steps": [
                {
                    "name": "gcr.io/cloud-builders/docker",
                    "args": [
                        "build",
                        "-t",
                        "gcr.io/PROJECT_ID/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "gcr.io/PROJECT_ID/IMAGE_NAME"
                ],
                "projectId": PROJECT_ID,
                "logsBucket": "gs://...",
                "sourceProvenance": {
                    "resolvedConnectedRepository": {
                        "repository": "REPOSITORY",
                        "revision": "REVISION.tar.gz"
                        "generation": "..."
                    }
                },
                "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID"
            }
        }
    }

    The JSON response is modeled using the Operation resource in the Cloud Build API. The metadata field is modeled using the Build resource. The QUEUED status indicates that the build is awaiting execution.

What's next