diff --git a/docs/eventlisteners.md b/docs/eventlisteners.md index bcd9aafad..a93ac4e8d 100644 --- a/docs/eventlisteners.md +++ b/docs/eventlisteners.md @@ -72,7 +72,6 @@ EventListener sink uses to create the Tekton resources. The ServiceAccount needs a role with the following rules: - ```YAML kind: Role apiVersion: rbac.authorization.k8s.io/v1 @@ -92,6 +91,7 @@ rules: verbs: ["create"] ``` + If your EventListener is using [`ClusterTriggerBindings`](./clustertriggerbindings.md), you'll need a ServiceAccount with a @@ -200,7 +200,6 @@ if desired. The response body and headers of the last Interceptor is used for resource binding/templating. - ```YAML --- apiVersion: tekton.dev/v1alpha1 @@ -231,6 +230,7 @@ spec: name: pipeline-template ``` + ### GitHub Interceptors GitHub Interceptors contain logic to validate and filter webhooks that come from @@ -252,7 +252,6 @@ The body/header of the incoming request will be preserved in this Interceptor's response. - ```YAML --- apiVersion: tekton.dev/v1alpha1 @@ -276,6 +275,7 @@ spec: name: pipeline-template ``` + ### GitLab Interceptors GitLab Interceptors contain logic to validate and filter requests that come from @@ -321,21 +321,55 @@ spec: ### CEL Interceptors -CEL Interceptors parse expressions to filter requests based on JSON bodies and -request headers, using the [CEL](https://github.com/google/cel-go) expression -language. Please read the -[cel-spec language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md) -for more details on the expression language syntax. +CEL Interceptors can be used to filter or modify incoming events, using the +[CEL](https://github.com/google/cel-go) expression language. -In addition to the standard -[CEL expression language syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md), -Triggers supports these additional [CEL expressions](./cel_expressions.md). +Please read the [cel-spec language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md) for +more details on the expression language syntax. + +The `cel-trig-with-matches` trigger below filters events that don't have an +`'X-GitHub-Event'` header matching `'pull_request'`. + +It also modifies the incoming request, adding an extra key to the JSON body, +with a truncated string coming from the hook body. + + +```YAML +apiVersion: tekton.dev/v1alpha1 +kind: EventListener +metadata: + name: cel-listener-interceptor +spec: + serviceAccountName: tekton-triggers-example-sa + triggers: + - name: cel-trig-with-matches + interceptors: + - cel: + filter: "header.match('X-GitHub-Event', 'pull_request')" + overlays: + - key: extensions.truncated_sha + expression: "truncate(body.pull_request.head.sha, 7)" + bindings: + - name: pipeline-binding + template: + name: pipeline-template + - name: cel-trig-with-canonical + interceptors: + - cel: + filter: "header.canonical('X-GitHub-Event') == 'push'" + bindings: + - name: pipeline-binding + template: + name: pipeline-template +``` + +In addition to the standard expressions provided by CEL, Triggers supports some +useful functions for dealing with event data [CEL expressions](./cel_expressions.md). The body/header of the incoming request will be preserved in this Interceptor's response. - ```YAML apiVersion: tekton.dev/v1alpha1 kind: EventListener @@ -365,12 +399,14 @@ spec: name: pipeline-template ``` -If no filter is provided, then the overlays will be applied to the body. With a -filter, the `expression` must return a `true` value, otherwise the request will -be filtered out. - +The `filter` expression must return a `true` value if this trigger is to +be processed, and the `overlays` applied. +Optionally, no `filter` expression can be provided, and the `overlays` will be +applied to the incoming body. + + ```YAML apiVersion: tekton.dev/v1alpha1 kind: EventListener @@ -391,6 +427,106 @@ spec: name: pipeline-template ``` + +#### Overlays + +The CEL interceptor supports "overlays", these are CEL expressions that are +applied to the body before it's returned to the event-listener. + + +```YAML +apiVersion: tekton.dev/v1alpha1 +kind: EventListener +metadata: + name: example-with-multiple-overlays +spec: + serviceAccountName: tekton-triggers-example-sa + triggers: + - name: cel-trig + interceptors: + - cel: + overlays: + - key: extensions.truncated_sha + expression: "truncate(body.pull_request.head.sha, 7)" + - key: extensions.branch_name + expression: "truncate(body.ref.split, '/')[2]" + bindings: + - name: pipeline-binding + template: + name: pipeline-template +``` + +In this example, the bindings will see two additional fields: + +Assuming that the input body looked something like this: +```json +{ + "ref": "refs/heads/master", + "pull_request": { + "head": { + "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", + } + } +} +``` + +The output body would look like this: + +```json +{ + "ref": "refs/heads/master", + "pull_request": { + "head": { + "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", + }, + }, + "extensions": { + "truncated_sha": "6113728", + "branch_name": "master" + } +} +``` +The `key` element of the overlay can create new elements in a body, or, +overlay existing elements. + +For example, this expression: + +```YAML +- key: body.pull_request.head.short_sha + expression: "truncate(body.pull_request.head.sha, 7)" +``` +Would see the `short_sha` being inserted into the existing body: + +```json +{ + "ref": "refs/heads/master", + "pull_request": { + "head": { + "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", + "short_sha": "6113728" + }, + } +} +``` +It's even possible to replace existing fields, by providing a key that matches +the path to an existing value. + +Anything that is applied as an overlay can be extracted using a binding e.g. + + +```YAML +apiVersion: tekton.dev/v1alpha1 +kind: TriggerBinding +metadata: + name: pipeline-binding-with-cel-extensions +spec: + params: + - name: gitrevision + value: $(body.extensions.branch_name) + - name: branch + value: $(body.pull_request.head.short_sha) +``` + ## Examples For complete examples, see diff --git a/examples/eventlisteners/cel-eventlistener-multiple-overlays.yaml b/examples/eventlisteners/cel-eventlistener-multiple-overlays.yaml new file mode 100644 index 000000000..d121aede2 --- /dev/null +++ b/examples/eventlisteners/cel-eventlistener-multiple-overlays.yaml @@ -0,0 +1,19 @@ +apiVersion: tekton.dev/v1alpha1 +kind: EventListener +metadata: + name: example-with-multiple-overlays +spec: + serviceAccountName: tekton-triggers-example-sa + triggers: + - name: cel-trig + interceptors: + - cel: + overlays: + - key: extensions.truncated_sha + expression: "truncate(body.pull_request.head.sha, 7)" + - key: extensions.branch_name + expression: "truncate(body.ref.split, '/')[2]" + bindings: + - name: pipeline-binding + template: + name: pipeline-template diff --git a/examples/triggerbindings/cel-example-trigger-binding.yaml b/examples/triggerbindings/cel-example-trigger-binding.yaml new file mode 100644 index 000000000..07f65cbd0 --- /dev/null +++ b/examples/triggerbindings/cel-example-trigger-binding.yaml @@ -0,0 +1,10 @@ +apiVersion: tekton.dev/v1alpha1 +kind: TriggerBinding +metadata: + name: pipeline-binding-with-cel-extensions +spec: + params: + - name: gitrevision + value: $(body.extensions.branch_name) + - name: branch + value: $(body.pull_request.head.short_sha)