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, build using a build config file.
- To build using a
Dockerfile
, have yourDockerfile
ready. - If your build requires source code, have your source code ready.
Required IAM permissions
- If you're storing build logs in the default logs bucket, you require the Project Viewer role and the Cloud Build Editor role to run a build.
- If you're storing build logs in the user-created logs bucket, you require the Cloud Build Editor role to run a build.
For instructions on granting IAM roles, see Configure access to Cloud Build resources.
Running builds
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 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.io/project-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 2016-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-code
where:
- build-config is the path to the build config file.
- source-code is the path or URL source code.
When you run gcloud builds submit
for the first time in a 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 submits the cloudbuild.yaml
build request
using archived source code stored in a Cloud Storage bucket.
gcloud builds submit --region=us-west2 --config cloudbuild.yaml \
gs://cloud-build-examples/node-docker-example.tar.gz
You can use .
to specify that the source code is in the current working
directory:
gcloud builds submit --region=us-west2 --config cloudbuild.yaml .
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
:
Create a file named
request.json
with the following contents:{ "source": { "storageSource": { "bucket": "cloud-build-examples", "object": "node-docker-example.tar.gz" } }, "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/$PROJECT_ID/my-image", "." ] }], "images": [ "gcr.io/$PROJECT_ID/my-image" ] }
In this build request, Cloud Build calls the
docker
build step with the argumentsbuild -t gcr.io/$PROJECT_ID/cb-demo-img .
.The full name of the image to be built is
gcr.io/$PROJECT_ID/cb-demo-img
. Images pushed to Container Registry use the registry name format.The code source for the build is in a compressed
tar
archive,node-docker-example.tar.gz
. The file is stored in a Cloud Storage bucket namedcloud-build-examples
.Run the following command where
project-id
is your 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
sendsrequest.json
in a POST call to thebuilds
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": "cloud-build-examples", "object": "node-docker-example.tar.gz" } }, "createTime": "2017-05-12T18:58:07.341526Z", "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/$PROJECT-ID/cb-demo-img", "." ] } ], "timeout": "600s", "images": [ "gcr.io/$PROJECT-ID/cb-demo-img" ], "projectId": $PROJECT-ID, "logsBucket": "gs://...", "sourceProvenance": { "resolvedStorageSource": { "bucket": "cloud-build-examples", "object": "node-docker-example.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. Themetadata
field is modeled using theBuild
resource. TheQUEUED
status indicates that the build is awaiting execution.
What's next
- Learn how to create manual triggers.
- Learn how to view build results.
- Learn how to troubleshoot build errors.