Google Cloud Build enables you to build container images and other artifacts from application source code. You can configure builds to fetch dependencies, run unit tests, static analyses, and integration tests, and create artifacts with build tools like docker, gradle, maven, bazel, and gulp. Builds run on Google-hosted infrastructure with 120 free build minutes a day and up to 10 concurrent builds.
This Jenkins plugin allows you to call Cloud Build as a build step.
Prerequisites
-
In order to run Google Cloud Build, you must set up a Google Cloud account and enable the API.
-
You must have a Jenkins instance set up and running.
-
The Cloud Build plugin uses google-oauth-plugin to allow the user to specify credentials for connecting to the cloud instance. You will need to create a Service Account key in the Google Cloud project, then in Jenkins select Google Service Account from private key and upload the private key. Alternatively, if your Jenkins master is running on Google Compute Engine, credentials may be obtained from the metadata server. See the google oauth plugin instructions for more details and links.
-
Some of the examples below use the google-storage-plugin to upload and download files from Google Cloud Storage. Please refer to the google-storage-plugin instructions for more details on its usage.
Hello world
The Google Cloud Build Plugin takes a build request in JSON or YAML, in the same format as is accepted by Cloud Build through curl or through gcloud, and sends it to the cloud. See Writing Custom Build Requests for more information on composing the build request.
The Build step requires selecting the credentials that were configured above, and the Build Request. The build request may be specified inline (as demonstrated below), or from a file located in the Jenkins workspace.
After the command is sent, the plugin polls the Cloud Build to check the status. If the step fails, the Jenkins step is failed. If it succeeds, the Jenkins step succeeds.
{width="700"}
In this example, the build request runs a simple step: in the Ubuntu docker image, which is available by default, it runs the command "echo hello world".
Once the build has started, a link to the build log in Google Cloud Console will be appear in the side panel under the Jenkins build.
{width="350"}
Custom substitutions
The input for this plugin is compatible with the YAML files you would use with curl or gcloud. To maintain this compatibility, we do not perform any Jenkins substitutions on the build request. For example, if the build request contains the string "$BUILD_ID", it will be passed as-is to Cloud Build, which will interpret it as a built-in substitution (in this case, $BUILD_ID will be replaced by Cloud Build's build ID).
To allow customization using Jenkins variables, the plugin allows adding user-defined substitutions, in the same format as in the build request. The value of the custom substitutions is interpreted using the standard Jenkins rules. The example below shows how Jenkins variables can be used in a build request:
The "Key" fields are subject to the same constraints as the user-defined substitutions in Cloud Build. The "Value" fields for _CUSTOM1 and _CUSTOM2 are interpreted through Jenkins at runtime, and the bindings are passed to Cloud Build.
{width="700"}
Attaching Source Code
To attach source code to your Google Cloud Build build request, check the "Attach source" box, select the type of source you wish to attach, and complete the associated fields. You may attach source code from the local workspace, from Google Cloud Storage, or from a Google Cloud Source Repository.
Local
This option is useful, for example, if you use another Jenkins plugin to download source code into your local workspace. Specify the path to the directory within the Jenkins workspace whose contents you wish to attach. This directory will be archived and uploaded to a temporary bucket in Google Cloud Storage.
{width="700"}
Once the build starts, a link to the Google Cloud Storage bucket (in Cloud Console) will appear in the side panel for the Jenkins build.
{width="350"}
Google Cloud Storage
If you already have an archive of your source stored in Google Cloud Storage (for example, an archive uploaded in a previous step using the google-storage-plugin), provide the bucket name and the path within the bucket to the archive.
{width="700"}
Once the build starts, a link to the Google Cloud Storage bucket (in Cloud Console) will appear in the side panel for the Jenkins build.
Google Cloud Source Repository
If your code is hosted in a Google Cloud Source Repository, specify the project ID (if different from the project associated with your credentials), repository name (if other than "default"), and the branch, tag, or commit from which you wish to build.
{width="700"}
To attach a source repository from a project other than the project associated with your credentials, the requestor's service account as a member with read access to the source repository. To obtain the service account email, either look up the Cloud Build service account, or simply try this step without permissions and get the email from the error message.
Once the build starts, a link to the Google Cloud Source Repository (in Cloud Platform Console) will appear in the side panel for the Jenkins build.
{width="350"}
Pipeline as Code
Jenkins Pipeline allows for the build/test/deploy pipeline to be specified in the form of Groovy code, which may be stored in a file (Jenkinsfile) included alongside the rest of the source code under version control. Cloud Build may also be invoked from a pipeline. For example:
node {
stage('Build') {
def message = 'Hello, World!'
googleCloudBuild \
credentialsId: 'my-project',
source: local('src'),
request: file('cloudbuild.yaml'),
substitutions: [
_CUSTOM1: message,
_CUSTOM2: "Lorem ipsum, dolor sit amet."
]
}
}
This example archives the contents of the src directory and uploads the
resulting tgz-file to Cloud Storage. The build request stored in
cloudbuild.yaml is then sent to Cloud Build using the credentials for
the my-project and with the custom variables _CUSTOM1 and _CUSTOM2
attached to the request.
The googleCloudBuild function accepts the following parameters:
credentialsId (required) - the string identifying which
credentials (provided by the Google OAuth plugin) to send in the request
request (required) - the build request to send to Cloud Build.
This must be one of the following:
-
file(filename)- sends the contents of filename as the build request -
inline(request)- sends request (a YAML or JSON string) as the build request
source (optional) - the source to attach to the build request. If
provided, this must be one of the following:
-
local(path)- archives the contents of path, uploads the resulting tgz to Cloud Storage and uses that as the source in the build request -
storage(bucket:bucket, object:object)- uses an existing Cloud Storage object as the source in the build request -
repo(projectId:projectId, repoName:repoName, branch:branch, tag:tag, commit:commit)- uses a Cloud Source Repository as the source in the build request. Exactly one of branch, tag, or commit must be specified. The projectId and repoName parameters may be omitted, in which case the same semantics are used as described in the API documentation
substitutions (optional) - a map indicating the custom
substitutions to include in the request