Cloud Build uses Common Expression Language (CEL), an open-source language used to evaluate expressions, to filter on build events. Cloud Build provides CEL support for notifiers and webhook triggers.
This page explains how you can filter build events using CEL.
CEL support
This section discusses Cloud Build features that support CEL.
Webhook triggers
Cloud Build provides CEL support when defining your
webhook trigger. You can set up custom filters
to invoke builds on incoming payload events that match the criteria
you specify in your filter. For example, you can create a webhook
trigger that invokes builds in response to a push to a specific
branch such as refs/heads/main
. In the example below, the _BRANCH
variable refers to the body of an incoming payload event:
_BRANCH == refs/heads/main
To learn more about how filters can be used in webhook triggers, see Creating webhook triggers.
Cloud Build notifiers
Cloud Build provides CEL support in the filter
string
in notifier config files. In your notifier configuration file, you can
specify the filter
string to filter on build events. The example below
shows a notifier config file that uses the filter
string to filter
on build events with a SUCCESS
status:
apiVersion: cloud-build-notifiers/v1
kind: my-notifier
metadata:
name: my-notifier-one
spec:
notification:
filter: build.status == Build.Status.SUCCESS
delivery:
url: https://notifier.com/one
To view a complete example of a notifier config file, see example files for the Slack, SMTP, or HTTP notifier.
Filtering examples
Cloud Build uses CEL with the variable, build
, on fields
listed in the Build
resource to access fields associated with your build event such as
your trigger ID, image list, or substitution values. You can use the filter
string to filter build events in your notifier config file using
any field listed in the Build
resource. To find the exact syntax associated with your field, see the
cloudbuild.proto
file.
Filtering by trigger ID
To filter by trigger ID, specify the value of your trigger ID in the filter
field using build.build_trigger_id
, where trigger-id
is
your trigger ID as a string:
filter: build.build_trigger_id == trigger-id
Filtering by status
To filter by status, specify the build status you want to filter on
in the filter
field using build.status
.
The following example shows how to filter build events with a SUCCESS
status using the filter
field:
filter: build.status == Build.Status.SUCCESS
You can also filter builds with varying statuses. The following example shows
how to filter build events that have a SUCCESS
, FAILURE
, or
TIMEOUT
status using the filter
field:
filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]
To see additional status values you can filter by, see Status under the Build resource reference.
Filtering by tag
To filter by tag, specify the value of your tag in the filter
field using build.tags
, where tag-name
is
the name of your tag:
filter: tag-name in build.tags
You can filter based on the number of tags specified in your build event
using size
. In the following example, the filter
field filters
build events that have exactly two tags specified with one tag specified as
v1
:
filter: size(build.tags) == 2 && "v1" in build.tags
Filtering by images
To filter by images, specify the value of your image in the filter
field
using build.images
, where image-name
is the full name
of your image as listed in Container Registry such as gcr.io/example/image-one
:
filter: image-name in build.images
In the following example, the filter
filters on build events that have
either gcr.io/example/image-one
or gcr.io/example/image-two
specified as
image names:
filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images
Filtering by time
You can filter build events based on a build's create time, start time, or
finish time by specifying one of the following options in your filter
field: build.create_time
, build.start_time
, or build.finish_time
.
In the following example, the filter
field uses timestamp
to filter
build events with a request time to create the build at July 20, 2020 at 6:00 AM:
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
You can also filter on build events by time comparisons. In the following example,
the filter
field uses timestamp
to filter build events with a start time
between July 20, 2020 at 6:00 AM and July 30, 2020 at 6:00 AM.
filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")
To learn more about how timezones are expressed in CEL, see the language definition for timezones.
To filter by duration of a build, you can use duration
to compare timestamps.
In the following example, the filter
field uses duration
to filter
build events with a builds that run for at least five minutes:
filter: build.finish_time - build.start_time >= duration("5m")
Filtering by substitution
You can filter by substitution by specifying the substitution variable
in the filter
field using build.substitutions
. In the following example,
the filter
field lists builds that contain the substitution variable
substitution-variable and checks if the substitution-variable matches the specified substitution-value:
filter: build.substitutions[substitution-variable] == substitution-value
Where:
substitution-variable
is the name of your substitution variable.substitution-value
is the name of your substitution value.
You can also filter by default substitution variable values. In the following
example, the filter
field lists builds that have the branch name master
and builds that have the repository name github.com/user/my-example-repo
. The
default substitution variables BRANCH_NAME
and REPO_NAME
are passed in
as keys to the build.substitutions
:
filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"
If you want to filter on strings using regular expressions, you can use the
built-in matches
function. In the example below, the filter
field filters
for builds with a status of FAILURE or TIMEOUT and that also have a build
substitution variable TAG_NAME
with a value that matches the regular expression
v{DIGIT}.{DIGIT}.{3 DIGITS})
.
filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`
To see a list of default substitution values, see Using default substitutions.
What's next
- Learn more about Common Expression Language (CEL).
- Learn how to create webhook triggers.
- Learn how configure notifications on specific build events using the Slack, SMTP, or HTTP notifier.