Tekton – Triggers and EventListeners

Vault: Install and set up Tekton Triggers

Mon, 01 Jan 0001 00:00:00 +0000

This document shows you how to install and set up Tekton Triggers.

Prerequisites

Kubernetes cluster version 1.18 or later.
Kubectl.
Tekton Pipelines.
Grant cluster-admin privileges to the user that installed Tekton Pipelines. See the kubernetes role-based access control (RBAC) docs.

Installation

Log on to your Kubernetes cluster with the same user account that installed Tekton Pipelines.

Depending on which version of Tekton Triggers you want to install, run one of the following commands:

Latest official release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.yaml

Nightly release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases-nightly/triggers/latest/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases-nightly/triggers/latest/interceptors.yaml

Specific Release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/previous/VERSION_NUMBER/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/previous/VERSION_NUMBER/interceptors.yaml

Replace VERSION_NUMBER with the numbered version you want to install. For example, v0.19.1.

Untagged Release

If your container runtime does not support image-reference:tag@digest (for example, cri-o used in OpenShift 4.x):

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/release.notags.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.notags.yaml

To monitor the installation, run:
```
kubectl get pods --namespace tekton-pipelines --watch
```
When all components show 1/1 under the READY column, the installation is complete. Hit Ctrl + C to stop monitoring.

Customization options

You can customize the behavior of the Triggers Controller changing some values in the config/feature-flags-triggers.yaml file.

Enable alpha features. Set the value of enable-api-fields: to "alpha", the default value is "stable". This flag only applies to the v1beta1 API version.
Exclude labels. Set the labels-exclusion-pattern: field to a regex pattern. Labels that match this pattern are excluded from getting added to the resources created by the EventListener. By default this field is empty, so all labels added to the EventListener are propagated down.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`EventListeners`

An EventListener is a Kubernetes object that listens for events at a specified port on your Kubernetes cluster. It exposes an addressable sink that receives incoming event and specifies one or more Triggers. The sink is a Kubernetes service running the sink logic inside a dedicated Pod.

Each Trigger, in turn, allows you to specify one or more TriggerBindings that allow you to extract fields and their values from event payloads, and one or more TriggerTemplates that receive field values from the corresponding TriggerBindings and allow Tekton Triggers to instantiate resources such as TaskRuns and PipelineRuns with that data.

If you need to modify, filter, or validate the event payload data before passing it to a TriggerBinding, you can optionally specify one or more Interceptors.

Structure of an `EventListener`

An EventListener definition consists of the following fields:

Required:
- apiVersion - specifies the target API version, for example triggers.tekton.dev/v1alpha1
- kind - specifies that this Kubernetes resource is an EventListener object
- metadata - specifies data that uniquely identifies this EventListener object, for example a name
- spec - specifies the configuration of your EventListener:
  - serviceAccountName - Specifies the ServiceAccount the EventListener will use to instantiate Tekton resources
Optional:
- triggers - specifies a list of Triggers to execute upon event detection
- cloudEventURI - specifies the URI for cloudevent sink
- resources - specifies the resources that will be available to the event listening service
- namespaceSelector - specifies the namespace for the EventListener; this is where the EventListener looks for the specified Triggers and stores the Tekton objects it instantiates upon event detection
- labelSelector - specifies the labels for which your EventListener recognizes Triggers and instantiates the specified Tekton objects

See our Tekton Triggers examples for ready-to-use example EventListener definitions.

Specifying the Kubernetes service account

You must specify a Kubernetes service account in the serviceAccountName field that the EventListener will use to instantiate Tekton objects.

Tekton Trigger creates 2 clusterroles while installing with necessary permissions required for an eventlistener. You can directly create bindings for your serviceaccount with the clusterroles.

A Kubernetes RoleBinding with tekton-triggers-eventlistener-roles clusterrole.
A Kubernetes ClusterRoleBinding with tekton-triggers-eventlistener-clusterroles clusterrole.

You can checkout an example here.
If you’re using namespaceSelectors in your EventListener, you will have to create an additional ClusterRoleBinding with tekton-triggers-eventlistener-roles clusterrole.

Specifying `Triggers`

You can optionally specify one or more Triggers that define the actions to take when the EventListener detects a qualifying event. You can specify either a reference to an external Trigger object or reference/define the TriggerBindings, TriggerTemplates, and Interceptors in the Trigger definition. A Trigger definition specifies the following fields:

name - (optional) a valid Kubernetes name that uniquely identifies the Trigger
interceptors - (optional) a list of Interceptors that will process event payload data before passing it to the associated TriggerBinding
bindings - (optional) a list of TriggerBindings for this Trigger; you can either reference existing TriggerBindings or embed their definitions directly
template - (optional) a TriggerTemplate for this Trigger; you can either reference an existing TriggerTemplate or embed its definition directly
triggerRef - (optional) a reference to an external Trigger

Below is an example Trigger definition that references the desired TriggerBindings, TriggerTemplates, and Interceptors:

triggers:
  - name: trigger-1
    interceptors:
      - github:
          eventTypes: ["pull_request"]
    bindings:
      - ref: pipeline-binding # Reference to a TriggerBinding object
      - name: message # Embedded Binding
        value: Hello from the Triggers EventListener!
    template:
      ref: pipeline-template

Below is an example Trigger definition that specifies a reference to an external Trigger object:

triggers:
    - triggerRef: trigger

Below is an example Trigger definition that embeds a triggerTemplate definition directly:

triggers:
  - name: "my-trigger"
    template:
      spec:
        params:
          - name: "my-param-name"
        resourceTemplates:
        - apiVersion: "tekton.dev/v1beta1"
          kind: TaskRun
          metadata:
            generateName: "pr-run-"
          spec:
            taskSpec:
              steps:
              - image: ubuntu
                script: echo "hello there"

Below is an example Trigger definition tailored to a multi-tenant scenario in which you may not want all of your Trigger objects to have the same permissions as the EventListener. In such case, you can specify a different service account at the Trigger level. This service account overrides the service account specified in the EventListener.

triggers:
  - name: trigger-1
    serviceAccountName: trigger-1-sa
    interceptors:
      - github:
          eventTypes: ["pull_request"]
    bindings:
      - ref: pipeline-binding
      - ref: message-binding
    template:
      ref: pipeline-template

You must update the Role assigned to the service account specified in the EventListener as shown below to allow it to impersonate the service account specified in the Trigger:

rules:
- apiGroups: [""]
  resources: ["serviceaccounts"]
  verbs: ["impersonate"]

Specifying `cloudEventURI`

Specifying the URI for cloud event sink which receives cloud events during Trigger Processing.

spec:
  cloudEventURI: http://eventlistener.free.beeceptor.com

Specifying `TriggerGroups`

TriggerGroups is a feature that allows you to specify a set of interceptors that will process before a set of Trigger resources are processed by the eventlistener. The goal of this feature is described in TEP-0053. TriggerGroups allow for a common set of interceptors to be defined inline in the EventListenerSpec before Triggers are invoked.

A TriggerGroup definition specifies the following fields:

name - (optional) a valid Kubernetes name that uniquely identifies the TriggerGroup
interceptors - a list of Interceptors that will process event payload data before passing it to the downstream Triggers
triggerSelector - a combination of a Kubernetes labelSelector and a namespaceSelector as defined later in this document. These two fields work together to define the Triggers that will be processed once Interceptors processing completes.

Below is an example EventListener that defines an inline triggerGroup:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  triggerGroups:
  - name: github-pr-group
    interceptors:
    - name: "validate GitHub payload and filter on eventType"
      ref:
        name: "github"
      params:
      - name: "secretRef"
        value:
          secretName: github-secret
          secretKey: secretToken
      - name: "eventTypes"
        value: ["pull_request"]
    triggerSelector:
      labelSelector:
        matchLabels:
          type: github-pr

This configuration would first process any event that is sent to the EventListener and determine if it matches the outlined conditions. If it passes these conditions, it will use the triggerSelector matching criteria to determine the target Trigger resources to continue processing.

Any extensions fields added during triggerGroup processing are passed to the downstream Trigger execution. This allows for shared data across all Triggers that are processed after group execution completes. As an example, extensions.myfield would be available to all Trigger resources matched by this group:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  triggerGroups:
  - name: cel-filter-group
    interceptors:
    - name: "validate body and add field"
      ref:
        name: "cel"
      params:
      - name: "filter"
        value: "body.action in ['opened', 'reopened']"
      - name: "overlays"
        value:
        - key: myfield
          expression: "body.pull_request.head.sha.truncate(7)"
    triggerSelector:
      namespaceSelector:
        matchNames:
        - foo
      labelSelector:
        matchLabels:
          type: cel-preprocessed

At this time, each TriggerGroup determines its own downstream Triggers, so if two separate groups select the same downstream Trigger resources, it may be executed multiple times. If you use this feature, ensure that Trigger resources are labeled to be queried by the appropriate set of TriggerGroups.

Specifying `Resources`

You can optionally customize the sink deployment for your EventListener using the resources field. It accepts the following types of objects:

Kubernetes Resource using the kubernetesResource field
Custom Resource objects via the CustomResource field

Legal values for the PodSpec sub-fields for both kubernetesResource and CustomResource are:

ServiceAccountName
NodeSelector
Tolerations
Containers
Affinity
TopologySpreadConstraints
SecurityContext

Legal values for the Containers sub-field for kubernetesResource and CustomResource are:

kubernetesResource:

Resources
Env
LivenessProbe
ReadinessProbe
StartupProbe
SecurityContext

CustomResource:

Resources
Env
SecurityContext

Specifying a `kubernetesResource` object

Below is an example resources: field definition specifying a kubernetesResource object:

spec:
  resources:
    kubernetesResource:
      serviceType: NodePort
      servicePort: 80
      spec:
        template:
          metadata:
            labels:
              key: "value"
            annotations:
              key: "value"
          spec:
            serviceAccountName: tekton-triggers-github-sa
            securityContext:
              runAsNonRoot: true
            nodeSelector:
              app: test
            tolerations:
            - key: key
              value: value
              operator: Equal
              effect: NoSchedule
            containers:
            - securityContext:
                readOnlyRootFilesystem: true

Specifying `Service` configuration

The type and port for the Service created for the EventListener can be configured via the ServiceType and ServicePort specifications respectively. By default, the Service type is set to ClusterIP and port is set to 8080.

spec:
  resources:
    kubernetesResource:
      serviceType: LoadBalancer
      servicePort: 8128

If you use a loadbalancer service, you can optionally define a LoadBalancerClass with the ServiceLoadBalancerClass attribute.

spec:
  resources:
    kubernetesResource:
      serviceType: LoadBalancer
      serviceLoadBalancerClass: internal

Specifying `Replicas`

You can optionally use the replicas field to instruct Tekton Triggers to deploy more than one instance of your EventListener in individual Kubernetes Pods. If you do not specify this value, the default number of instances (and thus, the number of respective Pods) per EventListener is 1. If you set a value for the replicas field while creating or upgrading the EventListener's YAML file, that value overrides any value you set manually later as well as a value set by any other deployment mechanism, such as HPA.

Specifying a `CustomResource` object

You can specify a Kubernetes Custom Resource object using the CustomResource field. This field has one sub-field, runtime.RawExtension that allows you to specify dynamic objects.

Contract for the `CustomResource` object

The CustomResource object must abide by the contract shown below.

Contract-mandated CRD structure for the spec field:

   spec:
     template:
       metadata:
       spec:

Contract-mandated CRD structure for the status field:

type EventListenerStatus struct {
  duckv1beta1.Status `json:",inline"`

  // EventListener is addressable via the DNS address of the sink.
  duckv1alpha1.AddressStatus `json:",inline"`
}

Note: The CRD must follow the WithPod{} spec.

Below is an example resources: field definition specifying a CustomResource object using a Knative Service:

Note: This example assumes that Knative is installed on your cluster.

spec:
  resources:
    customResource:
      apiVersion: serving.knative.dev/v1
      kind: Service
#      metadata:
#        name: knativeservice # name is optional; if not specified, Triggers substitutes the EventListener's name with an "el-" prefix, for example: el-github-knative-listener
      spec:
        template:
          spec:
            serviceAccountName: tekton-triggers-example-sa
            containers:
            - resources:
                requests:
                  memory: "64Mi"
                  cpu: "250m"
                limits:
                  memory: "128Mi"
                  cpu: "500m"

Specifying `Interceptors`

An Interceptor is a “catch-all” event processor for a specific platform that runs before the TriggerBinding. It allows you to perform payload filtering, verification (using a secret), transformation, define and test trigger conditions, and implement other useful processing. Once the event data passes through an Interceptor, it then goes to the Trigger before you pass the payload data to the TriggerBinding. You can also use an Interceptor to modify the behavior of the associated Trigger.

For more information, see Interceptors.

Constraining `EventListeners` to specific namespaces

You can optionally specify a list of namespaces in which your EventListener will search for Triggers and instantiate the specified Tekton objects using the namespaceSelector field.

If you omit this field, your EventListener will only recognize Triggers specified in its definition or found under one or more specified target labels.

Below is an example namespaceSelector field that configures the EventListener to use the foo and bar namespaces:

  namespaceSelector:
    matchNames:
    - foo
    - bar

If you want your EventListener to recognize Triggers across your entire cluster, use a wildcard between quote as the only namespace:

  namespaceSelector:
    matchNames:
    - "*"

At present, if an EventListeners has Triggers inside its own spec as well as namespace-selector, Triggers in spec as well as in selected namespaces will be processed for a request. Triggers inside EventListener spec when using namespace-selector mode is deprecated and ability to specify both will be removed.

Constraining `EventListeners` to specific labels

You can optionally specify the labels for which your EventListener recognizes Triggers and instantiates the specified Tekton objects using the labelSelector field. This field uses the standard Kubernetes labelSelector mechanism and supports the matchExpressions sub-field. If you omit the labelSelector field, the EventListener accepts all resource labels.

Below is an example labelSelector field definition that constrains your EventListener to only recognize Triggers within its own namespace that are labeled foo=bar:

  labelSelector:
    matchLabels:
      foo: bar

Below is an example labelSelector field definition that uses the matchExpression sub-field to specify expressions that allow the EventListener to recognize Triggers across all namespaces in the cluster:

  namespaceSelector:
    matchNames:
    - *
  labelSelector:
    matchExpressions:
      - {key: environment, operator: In, values: [dev,stage]}
      - {key: trigger-phase, operator: NotIn, values: [testing]}

Specifying `EventListener` timeouts

An EventListener times out if it cannot process an event request within a timeout specified in controller.yaml. The timeouts are as follows:

-el-readtimeout: Read timeout; default is 5 seconds.
-el-writetimeout: Write timeout; default is 40 seconds.
-el-idletimeout: Idle timeout; default is 120 seconds.
-el-timeouthandler: Server route handler timeout; default is 30 seconds.

Disabling Payload Validation

To disable incoming payload validation for an EventListener, you can define an annotation tekton.dev/payload-validation: false on EventListener.

apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: eventlistener
  annotations:
    tekton.dev/payload-validation: "false"

By default, payload validation is enabled and will be disabled only if the annotation is defined. Removing the annotation will enable the payload validation.

Labels in `EventListeners`

By default, each EventListener automatically attaches the following labels to all resources it instantiates:

Name	Description
triggers.tekton.dev/eventlistener	Name of the `EventListener` that instantiated the resource.
triggers.tekton.dev/trigger	Name of the `Trigger` that instantiated the resource.
triggers.tekton.dev/eventid	UID of the incoming event.

Note: Because they’re used as labels, EventListener and Trigger names must conform to the Kubernetes syntax and character set requirements.

Annotations in `EventListeners`

Tekton Triggers propagates all annotations that you include in your EventListener to the Kubernetes service and deployment created by that EventListener. Keep in mind that annotations propagated from the EventListener override annotations already present in its Kubernetes service and deployment.

Below is an example load balancer protocol annotation in an EventListener definition that automatically propagates to the EventListener's service:

apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: eventlistener
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: https

Understanding `EventListener` response

An EventListener responds with a 202 ACCEPTED HTTP response when the EventListener has been able to process the request and selected the appropriate triggers to process based off the EventListener configuration.

After detecting an event, the EventListener responds with the following message:

{
  "eventListener": "listener",
  "namespace": "default",
  "eventListenerUID": "ea71a6e4-9531-43a1-94fe-6136515d938c",
  "eventID": "14a657c3-6816-45bf-b214-4afdaefc4ebd"
}

eventListenerUID - UID of the target EventListener.
eventID - UID assigned to this event request

Response to CloudEvents

EventListener can acts as sink for CloudEvents. When it acts as such, then its response is different from above.

EventListener sends out this cloudevent as response assuming an EventListener with name listener in the default namespace with uuid ea71a6e4-9531-43a1-94fe-6136515d938c:

type: dev.tekton.event.triggers.accepted.v1
source: listener
subject: default.listener accepted eventID
id: 14a657c3-6816-45bf-b214-4afdaefc4ebd

id is assigned eventID.

It also has following data:

{
  "eventListener": "listener",
  "namespace": "default",
  "eventListenerUID": "ea71a6e4-9531-43a1-94fe-6136515d938c",
  "eventID": "14a657c3-6816-45bf-b214-4afdaefc4ebd"
}

eventID - UID assigned to this event request

Deprecated Fields

These fields are included in EventListener responses, but will be removed in a future release.

eventListener - name of the target EventListener. Use eventListenerUID instead.
namespace - namespace of the target EventListener. Use eventListenerUID instead.

TLS HTTPS support in `EventListeners`

Tekton Triggers supports both HTTP and TLS-based HTTPS connections. To configure your EventListener for TLS, add the TLS_CERT and TLS_KEY reserved environment variables using the secretKeyRef variable type, then specify a secret containing the cert and key files. See TEP-0027 and our TLS configuration example for more information.

Obtaining the status of deployed `EventListeners`

Use the following command to get a list of EventListeners deployed on your cluster along with their statuses:

kubectl get el

You will get a response similar to the following:

NAME                       ADDRESS                                                             AVAILABLE   REASON                     READY   REASON
tls-listener-interceptor   http://el-tls-listener-interceptor.default.svc.cluster.local        True        MinimumReplicasAvailable

Where for each returned line, the column values are, from left to right:

NAME - name of the EventListener
ADDRESS - IP address or URL of the EventListener
AVAILABLE - readiness state of the associated Deployment and Service
REASON - reason for the value displayed in the AVAILABLE column
READY - readiness state of the Kubernetes Custom Resource object specified in the EventListener
REASON - reason for the value displayed in the READY column

Note: The status messaging described above is being refactored. For more information, see Issue 932.

Configuring logging for `EventListeners`

You can configure logging for your EventListeners using the config-logging-triggers ConfigMap located in the tekton-pipelines namespace (config-logging.yaml). Tekton Triggers automatically reconciles this configmap into environment variables on your event listener deployment.

To access your EventListener logs, query your cluster for Pods whose eventlistener label matches the name of your EventListener object. For example:

kubectl get pods --selector eventlistener=my-eventlistener

Configuring metrics for `EventListeners`

The following pipeline metrics are available on the eventlistener Service on port 9000.

Name	Type	Labels/Tags	Status
`eventlistener_triggered_resources`	Counter	`kind`=<kind>	experimental
`eventlistener_event_received_count`	Counter	`status`=<status>	experimental
`eventlistener_http_duration_seconds_[bucket, sum, count]`	Histogram	-	experimental

Several kinds of exporters can be configured for an EventListener, including Prometheus, Google Stackdriver, and many others. You can configure metrics using the config-observability-triggers config map in the EventListener namespaces. There is a config-observability-triggers configmap in the tekton-pipelines namespace that can be configured for the operation of the Triggers webhook and controller components.

See the Knative documentation for more information about available exporters and configuration values.

Exposing an `EventListener` outside of the cluster

EventListeners create an underlying Kubernetes service (unless a user specifies a customResource EventListener deployment). By convention, this service is the same name as the EventListener prefixed with el. So, an EventListener named foo will create a service called el-foo.

This service, by default is of type ClusterIP which means it is only accessible within the cluster on which it is running. You can expose this service as you would with any regular Kubernetes service. A few ways are highlighted below:

Using a LoadBalancer Service type
Using a Kubernetes Ingress object
Using the NGINX Ingress Controller
Using OpenShift Route

Exposing an `EventListener` using a `LoadBalancer` Service

If your Kubernetes cluster supports external load balancers, you can set the serviceType field to LoadBalancer to switch the Kubernetes service type:

spec:
  resources:
    kubernetesResource:
      serviceType: LoadBalancer

Note: You can find the external IP of this service by running kubectl get svc/el-${EVENTLISTENER-NAME} -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'

Exposing an `EventListener` using a Kubernetes `Ingress` object

You can expose the service created by the EventListener using a regular Kubernetes Ingress. To do this, you may first have to change the serviceType to NodePort:

spec:
  resources:
    kubernetesResource:
      serviceType: NodePort

You can also use the Tekton create-ingress task to configure an Ingress object using self-signed certificates.

Exposing an `EventListener` using Openshift Route

Below are instructions for configuring an OpenShift 4.2 cluster running API version v1.14.6+32dc4a0. For more information, see Route Configuration.

Obtain the name of your EventListener service:

 oc get el <EVENTLISTENR_NAME> -o=jsonpath='{.status.configuration.generatedName}'

Expose the EventListener service:

 oc expose svc/[el-listener] # REPLACE el-listener WITH YOUR SERVICE NAME FROM STEP 1

Obtain the IP address of the exposed route:

 oc get route el-listener  -o=jsonpath='{.spec.host}' # REPLACE el-listener WITH YOUR SERVICE NAME FROM STEP 1

Test the configuration with curl or set up a GitHub Webhook that sends events to it.

Understanding the deployment of an `EventListener`

Below is a high-level walkthrough through the deployment of an EventListener using a GitHub example provided by Tekton Triggers.

Instantiate the example EventListener on your cluster:
```
kubectl create -f https://github.com/tektoncd/triggers/tree/main/examples/v1beta1/github
```
Tekton Triggers creates a new Deployment and Service for the EventListener. using the EventListener definition, metadata.labels, and pre-existing values such as container Image, Name, and Port. Tekton Triggers uses the EventListener name prefixed with el- to name the Deployment and Service when instantiating them. For example, if the EventListener name is foo, the Deployment and Service names are named el-foo.

Use kubectl to verify the Deployment is running on your cluster:

kubectl get deployment
NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
el-github-listener-interceptor   1/1     1            1           11s

Use kubectl to verify the Service is running on your cluster:

kubectl get svc
NAME                             TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
el-github-listener-interceptor   ClusterIP   10.99.188.140   <none>        8080/TCP   52s

Obtain the URL on which the EventListener is listening for events:

kubectl get eventlistener
NAME                          ADDRESS                                                              AVAILABLE   REASON
github-listener-interceptor   http://el-github-listener-interceptor.ptest.svc.cluster.local:8080   True        MinimumReplicasAvailable

See our GitHub EventListener example to try instantiating an EventListener locally.

Deploying `EventListeners` in multi-tenant scenarios

EventListeners are effectively Tekton clients that use HTTP to bypass the normal Kubernetes authentication mechanism established through kubeconfig files and the kubectl config command tree. Because of this, you must be conscious of your configuration decisions, such as:

How to securely expose each EventListener to the outside of your cluster,
How to securely control how each EventListener and its associated objects, such as Interceptors, interact with data on your cluster.

At the minimum, each EventListener specifies its own Kubernetes Service account as explained earlier, and it acts on all events it receives with the permissions of that service account. If your business needs mandate more granular permission control across the Triggers and Interceptors specified in your EventListeners, you have the following options:

Deploy each EventListener in its own namespace
Deploy multiple EventListeners in the same namespace
Specify a separate service account for each Trigger

Deploying each `EventListener` in its own namespace

In this scenario, you create multiple EventListeners that in turn use a variety of Triggers and Interceptors, each EventListener gets its own namespace. This way, you can use a different service account for each namespace and tailor the permissions of those accounts to the functionality of their corresponding EventListeners. Because creating a namespace often instantiates the necessary service accounts based on pre-configured permissions, this also simplifies the deployment process as you simply need to update the permissions associated with those accounts.

However, this approach has the following drawbacks:

Namespaces with separately associated Secrets and ServiceAccounts can be the most expensive items in the Kubernetes etcd store; on large clusters, the capacity of the etcd store can become a concern.
Since each EventListener requires its own HTTP port to listen for events, you must configure your network to allow access to each corresponding IP address and port combination unless you configure an ingress abstraction layer, such as the Kubernetes Ingress object,or OpenShift Route.

Deploying multiple `EventListeners` in the same namespace

In this scenario, you create multiple EventListeners in the same namespace. This will require customization of the associated service account(s), secret(s), and RBAC, since the automatically generated defaults are not always ideal, but you will not incur a significant etcd store cost as in the multiple namespace scenario. Network security and configuration overhead concerns, however, still apply as described earlier. You can also achieve a similar result by specifying a separate service account for each Trigger used across your EventListener pool at the cost of increased administration overhead.

Cloud Events during Trigger Processing

The cloud event that is sent to a target URI during Trigger processing. The types of events send for now are:

Type	Description
dev.tekton.event.triggers.started.v1	triggers processing started in eventlistener
dev.tekton.event.triggers.successful.v1	triggers processing successful and a resource created
dev.tekton.event.triggers.failed.v1	triggers failed in eventlistener
dev.tekton.event.triggers.done.v1	triggers processing done in eventlistener handle

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`TriggerTemplates`

A TriggerTemplate is a resource that specifies a blueprint for the resource, such as a TaskRun or PipelineRun, that you want to instantiate and/or execute when your EventListener detects an event. It exposes parameters that you can use anywhere within your resource’s template.

TriggerTemplates currently support the following Tekton Pipelines resources:

`v1alpha1`	`v1beta1`
`Pipeline`	`Pipeline`
`PipelineRun`	`PipelineRun`
`Task`	`Task`
`TaskRun`	`TaskRun`
`ClusterTask`	`ClusterTask`
`Condition`
`PipelineResource`

Structure of a `TriggerTemplate`

Below is an example TriggerTemplate definition:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: pipeline-template
spec:
  params:
  - name: gitrevision
    description: The git revision
    default: main
  - name: gitrepositoryurl
    description: The git repository url
  - name: message
    description: The message to print
    default: This is the default message
  - name: contenttype
    description: The Content-Type of the event
    default: text/plain
  resourcetemplates:
  - apiVersion: tekton.dev/v1beta1
    kind: PipelineRun
    metadata:
      generateName: simple-pipeline-run-
    spec:
      pipelineRef:
        name: simple-pipeline
      params:
      - name: message
        value: $(tt.params.message)
      - name: contenttype
        value: $(tt.params.contenttype)
      - name: git-revision
        value: $(tt.params.gitrevision)
      - name: git-url
        value: $(tt.params.gitrepositoryurl)
      workspaces:
      - name: git-source
        emptyDir: {}

Keep the following in mind:

If you don’t specify the namespace, Tekton resolves it to the namespace of the EventListener that specifies the given TriggerTemplate.
The $(uid) variable is implicitly available to the resource templates you specify in your TriggerTemplate with a random value, just like the postfix generated by the Kubernetes generateName metadata field. This can be useful for resource templates that use internal references.
Tekton adds the following labels to all resource templates within a TriggerTemplate:
- tekton.dev/eventlistenter:<EventListenerName> to help with housekeeping and garbage collection.
- tekton.dev/triggers-eventid:<EventID> to track resources created by a specific event.
To support arbitrary resource types, Tekton resolves resource templates internally as byte blobs. Because of this, Tekton only validates these resources when processing an event rather than at the creation of the TriggerTemplate. The default assigned cluster role to the EventListener service account only allows creating Tekton resources. You will need to add the appropriate roles to the EventListener’s service account to be able to create other non Tekton resources.
As of Tekton Pipelines 0.8.0, you can embed resource definitions directly in your TriggerTemplate definition. To prevent a race condition between creating and using resources, you must embed each resource definition within the PipelineRun or TaskRun that uses that resource.

Specifying parameters

A TriggerTemplate allows you to declare parameters supplied by the associated TriggerBinding and/or EventListener as follows:

Declare your parameters in the params section of the TriggerTemplate definition.
You must specify a name and can optionally specify a description and a default value.
Tekton applies the value of the default field for each entry in the params array of your TriggerTemplate if it can’t find a corresponding value in the associated TriggerBinding or cannot successfully extract the value from an HTTP header or body payload.
You can reference tt.params in the resourcetemplates section of your TriggerTemplate to make your TriggerTemplate reusable.
When you specify parameters in your resource template definitions, Tekton replaces the specified string with the parameter name, for example $(tt.params.name). Therefore, simple string and number value replacements work fine directly in your YAML file. However, if a string has a numerical prefix, such as 123abcd, Tekton can misinterpret it to be a number and throw an error. In such cases, enclose the affected parameter key in quotes (").

Embedding JSON objects within resource templates

Tekton no longer replaces quotes (") with escaped quotes (\") and does not perform any escaping on variables in your resource templates. If you are embedding JSON objects as variables in your templates, you must not enclose them with quotes ("). If you have existing TriggerTemplates that use escaped quotes, add an annotation to work around this behavior change.

For example, consider the following JSON object:

{
  "title": "this is \"demo\" body",
  "object": {
    "name": "testing"
  }
}

If your TriggerBinding extracts $(body.title) then Tekton inserts it into your TriggerTemplate as this is a \"demo\" body. To work around this, annotate the TriggerTemplate as follows:

apiVersion: triggers.tekton.dev/v1alpha1
kind: TriggerTemplate
metadata:
  name: escaped-tt
  annotations:
    triggers.tekton.dev/old-escape-quotes: "true"
spec:
  params:
  - name: title
    description: The title from the incoming body

This way, Tekton passes the value as this is a \""demo\"" body, which in itself is not valid JSON code; however, if you use a value with $(body.object) in a resource template that specifically passes it as a quoted string, then this workaround restores normal operation. This can also be useful for parsing a string containing JSON code in a command.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`TriggerBindings`

A TriggerBinding allows you to extract fields from an event payload and bind them to named parameters that can then be used in a TriggerTemplate. For instance, one can extract the commit SHA from an incoming event and pass it on to create a TaskRun that clones a repo at that particular commit.

Note: Trigger uses the parameter name to match TriggerBinding params to TriggerTemplate params. In order to pass information, the param name used in the binding must match the param name used in the template.

Structure of a `TriggerBinding`

There are 3 way of declaring a TriggerBinding:

Inline or embedded inside a Trigger
Using the TriggerBinding custom resource so that the binding params can be reused across multiple trigger
Using the ClusterTriggerBinding custom resource in order to promote reuse within an entire cluster

Inline bindings

The simplest way to declare bindings is within a Trigger itself:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: push-trigger
spec:
  bindings:
  - name: gitrevision
    value: $(body.head_commit.id)
  - name: gitrepositoryurl
    value: $(body.repository.url)
  template:
    ref: git-clone-template

`TriggerBindings`

The binding used above can be put in a TriggerBinding CRD in order to be reused across multiple triggers:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: pipeline-binding
spec:
  params:
  - name: gitrevision
    value: $(body.head_commit.id)
  - name: gitrepositoryurl
    value: $(body.repository.url)
  - name: contenttype
    value: $(header.Content-Type)

A Trigger resource can then refer to this binding:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: push-trigger
spec:
  bindings:
  - ref: pipeline-binding
  template:
    ref: git-clone-template

`ClusterTriggerBindings`

A ClusterTriggerBinding is a cluster-scoped TriggerBinding that you can reuse across your entire cluster. You can reference a ClusterTriggerBinding in any Trigger in any namespace. You can specify multiple ClusterTriggerBindings within your Trigger as well as specify the same ClusterTriggerBinding in multiple Triggers.

Below is an example ClusterTriggerBinding definition:

apiVersion: triggers.tekton.dev/v1beta1
kind: ClusterTriggerBinding
metadata:
  name: pipeline-clusterbinding
spec:
  params:
    - name: gitrevision
      value: $(body.head_commit.id)
    - name: gitrepositoryurl
      value: $(body.repository.url)
    - name: contenttype
      value: $(header.Content-Type)

When referencing a ClusterTriggerBinding, you must specify a kind value within the bindings field. The default is TriggerBinding which denotes a namespaced TriggerBinding. For example:

---
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: listener-clustertriggerbinding
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      bindings:
        - ref: pipeline-clusterbinding
          kind: ClusterTriggerBinding
        - ref: message-clusterbinding
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template

Specifying parameters

A TriggerBinding allows you to specify parameters (params) that Tekton passes to the corresponding TriggerTemplate. For each parameter, you must specify a name and a value field with the appropriate values.

Accessing data in HTTP JSON payloads

Tekton can use a TriggerBinding to access data in the headers and body of an HTTP JSON payload. To do so, it uses JSONPath expressions encapsulated within a $() wrapper. Keys in HTTP JSON headers are case-sensitive.

For example, below is a valid expression:

$(body.key1)
$(.body.key)

On the other hand, the expressions below are invalid:

.body.key1 # INVALID - Expression is not wrapped in `$()`.
$({body) # INVALID - Trailing curly brace is missing.

If a $() wrapper is embedded inside another $() wrapper, Tekton parses the contents of the innermost wrapper as the JSONPath expression. For example:

$($(body.b)) # Parsed as $(body.b)
$($($(body.b))) # Parsed as $(body.b)

Accessing data added by `Interceptors`

An interceptor can add additional useful data that can be used by a TriggerBinding. Data added by interceptors can be accessed under the top-level extensions field e.g. $(extensions.field-name). In the following example, the CEL interceptor adds a field that is then accessed by the trigger binding:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: push-trigger
spec:
  interceptors:
    - name: add-truncated-sha
      ref:
        name: "cel"
      params:
        - name: "overlays"
          value:
          - key: truncated_sha
            expression: "body.pull_request.head.sha.truncate(7)"
  bindings:
    - name: truncated_sha
      value: $(extensions.truncated_sha)
  template:
    ref: git-clone-template

Accessing EventListener Event Context

The EventListener has a set of internal data points that are maintained for the complete processing of a single event. These values are available for use in TriggerBinding objects.

This data can be accessed on the context parameter, as an example:

$(context.eventID) # access the internal eventID of the request

Accessing JSON keys containing special characters like (`.`) or (`/`)

To access a JSON key that contains a period (.), you must escape the period with a backslash (\.). For example:

# Body contains a `tekton.dev` field: {"body": {"dev.tekton.dev/foo": "triggers"}}
$(body.dev\.tekton\.dev\/foo) -> "triggers"

Fallback to default values

If Tekton fails to resolve the JSONPath expressions you have configured against the HTTP JSON payload, it falls back to the default value in the corresponding TriggerTemplate, if specified.

Field binding examples

Below are some examples of Tekton performing field binding based on the most commonly used field definitions:


`$(body)` -> replaced by the entire body

$(body) -> "{"key1": "value1", "key2": {"key3": "value3"}, "key4": ["value4", "value5", "value6"]}"

$(body.key1) -> "value1"

$(body.key2) -> "{"key3": "value3"}"

$(body.key2.key3) -> "value3"

$(body.key4[0]) -> "value4"

$(body.key4[0:2]) -> "{"value4", "value5"}"

# $(header) -> replaced by all headers from the event

$(header) -> "{"One":["one"], "Two":["one","two","three"]}"

$(header.One) -> "one"

$(header.one) -> "one"

$(header.Two) -> "one two three"

$(header.Two[1]) -> "two"

Specifying multiple bindings

You can specify multiple bindings within the Trigger definition in your EventListener. This allows you to reuse as well as mix-and-match your bindings across multiple Trigger definitions. For example, you can create a Trigger with a binding that extracts event data and another binding that provides information on the deployment environment:

apiVersion: triggers.tekton.dev/v1alpha1
kind: TriggerBinding
metadata:
  name: event-binding
spec:
  params:
    - name: gitrevision
      value: $(body.head_commit.id)
    - name: gitrepositoryurl
      value: $(body.repository.url)
---
apiVersion: triggers.tekton.dev/v1alpha1
kind: TriggerBinding
metadata:
  name: prod-env
spec:
  params:
    - name: environment
      value: prod
---
apiVersion: triggers.tekton.dev/v1alpha1
kind: TriggerBinding
metadata:
  name: staging-env
spec:
  params:
    - name: environment
      value: staging
---
apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: listener
spec:
  triggers:
    - name: prod-trigger
      bindings:
        - ref: event-binding
        - ref: prod-env
      template:
        ref: pipeline-template
    - name: staging-trigger
      bindings:
        - ref: event-binding
        - ref: staging-env
      template:
        ref: pipeline-template

Troubleshooting `TriggerBindings`

You can use the binding-eval tool to evaluate your TriggerBinding against a specific HTTP request to determine the parameters that Tekton generates from that request when your corresponding Trigger executes.

To install the binding-eval tool use the following command:

$ go install github.com/tektoncd/triggers/cmd/binding-eval@{version}

Below is an example of using the tool to evaluate a TriggerBinding:

$ cat testdata/triggerbinding.yaml
apiVersion: tekton.dev/v1alpha1
kind: TriggerBinding
metadata:
  name: pipeline-binding
spec:
  params:
  - name: foo
    value: $(body.test)
  - name: bar
    value: $(header.X-Header)

$ cat testdata/http.txt
POST /foo HTTP/1.1
Content-Length: 16
Content-Type: application/json
X-Header: tacocat

{"test": "body"}

$ binding-eval -b testdata/triggerbinding.yaml -r testdata/http.txt
[
  {
    "name": "foo",
    "value": "body"
  },
  {
    "name": "bar",
    "value": "tacocat"
  }
]

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`ClusterInterceptors`

Tekton Triggers ships with the ClusterInterceptor Custom Resource Definition (CRD), which allows you to implement a custom cluster-scoped Webhook-style Interceptor.

A ClusterInterceptor specifies an external Kubernetes v1 Service running custom business logic that receives the event payload from the EventListener via an HTTP request and returns a processed version of the payload along with an HTTP 200 response. The ClusterInterceptor can also halt processing if the event payload does not meet criteria you have configured as well as add extra fields that are accessible in the EventListener's top-level extensions field to other Interceptors and ClusterInterceptors chained with it and the associated TriggerBinding.

Structure of a `ClusterInterceptor`

A ClusterInterceptor definition consists of the following fields:

Required:
- apiVersion - specifies the target API version, for example triggers.tekton.dev/v1alpha1
- kind - specifies that this Kubernetes resource is a ClusterInterceptor object
- metadata - specifies data that uniquely identifies this ClusterInterceptor object, for example a name
- spec - specifies the configuration information for this ClusterInterceptor object, including:
  - [clientConfig] - specifies how a client, such as an EventListener communicates with this ClusterInterceptor object

Configuring the client of the `ClusterInterceptor`

The clientConfig field specifies the client, such as an EventListener and how it communicates with the ClusterInterceptor to exchange event payload and other data. You can configure this field in one of the following ways:

Specify the url field and as its value a URL at which the corresponding Kubernetes service listens for incoming requests from this ClusterInterceptor
Specify the service field and within it reference the corresponding Kubernetes service that’s listening for incoming requests from this ClusterInterceptor

For example:

spec:
  clientConfig:
    url: "http://interceptor-svc.default.svc/"
---
spec:
  clientConfig:
    service:
      name: "my-interceptor-svc"
      namespace: "default"
      path: "/optional-path" # optional
      port: 8081 # defaults to 80

Configuring a Kubernetes Service for the `ClusterInterceptor`

The Kubernetes object running the custom business logic for your ClusterInterceptor must meet the following criteria:

Fronted by a regular Kubernetes v1 Service listening on an HTTP port (default port is 80)
Accepts an HTTP POST request that contains an InterceptorRequest as a JSON body
Returns an HTTP 200 OK response that contains an InterceptorResponse as a JSON body. If the trigger processing should continue, the interceptor should set the continue field in the response to true. If the processing should be stopped, the interceptor should set the continue field to false and also provide additional information detailing the error in the status field.
Returns a response other than HTTP 200 OK only if payload processing halts due to a catastrophic failure.

Running ClusterInterceptor as HTTPS

Triggers now run clusterinterceptor as https server in order to support end to end secure connection and here is a TEP which gives more detail about this support.

By default Triggers run all core interceptor (GitHub, GitLab, BitBucket, CEL) as HTTPS.

Triggers expose a new optional field caBundle as part of clusterinterceptor spec.

Example:

spec:
  clientConfig:
    caBundle: <cert data>
    service:
      name: "my-interceptor-svc"
      namespace: "default"
      path: "/optional-path" # optional
      port: 8443

Triggers uses knative pkg to generate key, cert, cacert and fill caBundle for core interceptors (GitHub, GitLab, BitBucket, CEL).

Triggers now support writing custom interceptor for both http and https. Support of http for custom interceptor will be there for 1-2 releases, later it will be removed and only https will be supported.

End user who write https custom interceptor need to pass caBundle as well as label

  labels:
    server/type: https

to ClusterInterceptor in order to make secure connection with eventlistener.

Here is the reference for writing https server for custom interceptor.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Configuring `Interceptors`

Overview

An Interceptor is a “catch-all” event processor for a specific platform that runs before the TriggerBinding. It allows you to perform payload filtering, verification (using a secret), transformation, define and test trigger conditions, and implement other useful processing. Once the event data passes through an Interceptor, it then goes to the Trigger before you pass the payload data to the TriggerBinding. You can also use an Interceptor to modify the behavior of the associated Trigger.

Tekton Triggers currently supports two distinct Interceptor implementations:

Standalone Interceptors, which are instances of the Interceptor or the ClusterInterceptor Custom Resource Definition (CRD). You specify these Interceptors by referencing them, along with the desired parameters, within your EventListener. You can use the ClusterInterceptor CRD to implement your own custom Interceptors.
Legacy Interceptors, which you define entirely as part of the EventListener definition. This implementation will eventually be deprecated, so please consider transitioning to standalone Interceptors as soon as possible. See TEP-0026 for more context on this change.

Tekton Triggers ships with the following Interceptors to help you get started:

Specifying an `Interceptor`

To specify an Interceptor within your EventListener, create an interceptors: field with the following sub-fields:

name - (optional) a name that uniquely identifies this Interceptor definition
ref - a reference to a ClusterInterceptor or Interceptor object with the following fields:
- name - the name of the referenced ClusterInterceptor
- kind - (optional) specifies that whether the referenced Kubernetes object is a ClusterInterceptor object or NamespacedInterceptor. Default value is ClusterInterceptor
- apiVersion - (optional) specifies the target API version, for example triggers.tekton.dev/v1alpha1
- params - name/value pairs that specify the parameters you want to pass to the ClusterInterceptor
params - (optional) name/value pairs that specify the desired parameters for the Interceptor; the name field takes a string, while the value field takes a valid JSON object

Below is an example standalone Interceptor reference within an EventListener definition:

interceptors:
    - name: "validate GitHub payload and filter on eventType"
      ref:
        name: "github"
      params:
      - name: "secretRef"
        value:
          secretName: github-secret
          secretKey: secretToken
      - name: "eventTypes"
        value: ["pull_request"]
    - name: "CEL filter: only when PRs are opened"
      ref:
        name: "cel"
      params:
      - name: "filter"
        value: "body.action in ['opened', 'reopened']"

Webhook `Interceptors`

Note: Tekton Triggers ships with only a legacy Webhook Interceptor. If you want to implement it using the standalone model, see Implementing custom Interceptors.

A Webhook Interceptor allows you to process your event payload by an external Kubernetes object containing custom business logic. The Kubernetes object, exposed via a Kubernetes Service, receives event payload data from your EventListener via HTTP, applies its business logic to it, and returns the processed payload (both headers plus body) via a HTTP 200 response to the EventListener.

This payload can then continue on to the TriggerBinding specified in the EventListener. If processing is not successful, the Interceptor recognizes that the returned HTTP response code is not 200 and halts further processing of the event payload.

You can optionally specify additional data to merge with the event payload before sending out for processing by adding the data as canonical key/value pairs in the Interceptor's header field.

Your external Kubernetes object must meet the following criteria:

Fronted by a regular Kubernetes v1 Service running on HTTP port 80,
Accepts JSON payloads over HTTP,
Accepts HTTP POST requests with JSON payloads,
Returns an HTTP 200 OK response when you want the EventListener to continue processing the event,
Returns a JSON object in the HTTP response body.
Returns headers expected by subsequently chained Interceptors and the associated TriggerBinding.

Note: If your business logic does not modify either the HTTP payload’s header or body, simply return the same HTTP header or body that you received.

Below is an example Webhook Interceptor definition:

---
apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptors:
        - webhook:
            header:
              - name: Foo-Trig-Header1
                value: string-value
              - name: Foo-Trig-Header2
                value:
                  - array-val1
                  - array-val2
            objectRef:
              kind: Service
              name: gh-validate
              apiVersion: v1
              namespace: default
      bindings:
        - ref: pipeline-binding
      template:
        ref: pipeline-template

GitHub Interceptors

A GitHub Interceptor contains logic that validates and filters GitHub webhooks. It can validate the webhook’s origin as described in Securing your webhooks as well as filter incoming events by the criteria you specify. The GitHub Interceptor always preserves the payload data (both header and body) in its responses.

To use a GitHub Interceptor as a GitHub webhook validator, do the following:

Create a secret string value.
Configure the GitHub webhook with that value.
Create a Kubernetes secret containing your secret value.
Pass the Kubernetes secret as a reference to your GitHub Interceptor.

To use a GitHub Interceptor as a filter for event data, specify the event types you want the Interceptor to accept in the eventTypes field. The Interceptor accepts data event types listed in Event types and payloads.

Below is an example GitHub Interceptor reference:

 triggers:
    - name: github-listener
      interceptors:
        - ref:
            name: "github"
            kind: ClusterInterceptor
            apiVersion: triggers.tekton.dev
          params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["pull_request"]

For reference, below is an example legacy GitHub Interceptor definition:

  triggers:
    - name: github-listener
      interceptors:
        - github:
            secretRef:
              secretName: github-secret
              secretKey: secretToken
            eventTypes:

For more information, see our example of using this Interceptor.

Adding Changed Files

The GitHub Interceptor also has the ability to add a comma delimited list of all files that have changed (added, modified or deleted) for the push and pull_request events. The list of changed files are added to the changed_files property of the event payload in the top-level extensions field

Below is an example GitHub Interceptor that enables the addChangedFiles feature and uses the CEL Interceptor to filter incoming events by the files changed

 triggers:
    - name: github-listener
      interceptors:
        - ref:
            name: "github"
            kind: ClusterInterceptor
            apiVersion: triggers.tekton.dev
          params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["pull_request", "push"]
          - name: "addChangedFiles"
            value:
              enabled: true
        - ref:
            name: cel
          params:
          - name: filter
            # execute only when a file within the controllers directory has changed
            value: extensions.changed_files.matches('controllers/')

Adding Changed Files - Private Repository

The ability to add changed files can also work with private repositories by supplying a GitHub personal access token in the personalAccessToken field. In the example below, the personalAccessToken uses the github-pat secret to get the GitHub personal access token used to make the API calls to get the list of changed files.

 triggers:
    - name: github-listener
      interceptors:
        - ref:
            name: "github"
            kind: ClusterInterceptor
            apiVersion: triggers.tekton.dev
          params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["pull_request", "push"]
          - name: "addChangedFiles"
            value:
              enabled: true
              personalAccessToken:
                secretName: github-pat
                secretKey: token
        - ref:
            name: cel
          params:
          - name: filter
            # execute only when a file within the controllers directory has changed
            value: extensions.changed_files.matches('controllers/')

For more information around adding changed files, see the following examples

Owners validation for pull requests

The GitHub Interceptor supports the ability to halt processing on a pull request if the user is not listed in the owners file or is not a repository/organization member/owner. This feature can be used to prevent unnecessary execution of a PipelineRun or TaskRun. The GitHub Interceptor also supports the ability to trigger a PipelineRun/TaskRun through a comment that contains /ok-to-test on a pull request by an owner.

This feature will also work against private GitHub repositories by supplying a GitHub personal access token in the personalAccessToken field.

NOTE: Owners validation requires (at a minimum) the pull_request and issue_comment GitHub event types.

To use the GitHub Interceptor as a GitHub owners validator, do the following:

Create a secret string value.
Configure the GitHub webhook with that value.
Create a Kubernetes secret containing your secret value called SecretRef.
Pass the Kubernetes secret as a reference to your GitHub Interceptor.
Create an owners file and add the list of approvers into the approvers section.

Below is an example GitHub Interceptor using owners validation:

 triggers:
    - name: github-listener
      interceptors:
        - ref:
            name: "github"
            kind: ClusterInterceptor
            apiVersion: triggers.tekton.dev
          params:
            - name: "secretRef"
              value:
                secretName: github-secret
                secretKey: secretToken
            - name: "eventTypes"
              # Owners validation requires (at a minimum) the `pull_request` and `issue_comment` GitHub event types
              value: ["pull_request", "issue_comment"]
            - name: "githubOwners"
              value: 
                enabled: true
                # This value is needed for private repos or when checkType is set to orgMembers or repoMembers or all
                # personalAccessToken:
                #   secretName: github-token
                #   secretKey: secretToken
                checkType: none

For more information around owners file validation, see the following example

github-owners

GitLab Interceptors

A GitLab Interceptor contains logic that validates and filters GitLab webhooks. It can validate the webhook’s origin as described in Webhooks as well as filter incoming events by the criteria you specify. The GitLab Interceptor always preserves the payload data (both header and body) in its responses.

To use a GitLab Interceptor as a GitLab webhook validator, do the following:

Create a secret string value.
Configure the GitLab webhook with that value.
Create a Kubernetes secret containing your secret value.
Pass the Kubernetes secret as a reference to your GitLab Interceptor.

To use a GitLab Interceptor as a filter for event data, specify the event types you want the Interceptor to accept in the eventTypes field. The Interceptor accepts data event types listed in Events.

Below is an example GitLab Interceptor reference:

interceptors:
- ref:
    name: "gitlab"
  params:
  - name: "secretRef"
    value:
      secretName: foo
      secretKey: bar
  - name: "eventTypes"
    value: ["Push Hook"]

For reference, below is an example legacy GitLab Interceptor definition:

apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: gitlab-listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptors:
        - gitlab:
            secretRef:
              secretName: foo
              secretKey: bar
            eventTypes:
              - Push Hook
      bindings:
        - ref: pipeline-binding
      template:
        ref: pipeline-template

Bitbucket `Interceptors`

Bitbucket Interceptors has support for both Bitbucket server (which does secret validation and event filtering) and Bitbucket cloud (which does event filtering).

Bitbucket Server

A Bitbucket server contains logic that validates and filters Bitbucket server webhooks. It can validate the webhook’s origin as described in Webhooks. The Bitbucket Interceptor always preserves the payload data (both header and body) in its responses.

To use a Bitbucket Interceptor as a Bitbucket server webhook validator, do the following:

Create a secret string value.
Configure the Bitbucket server webhook with that value.
Create a Kubernetes secret containing your secret value.
Pass the Kubernetes secret as a reference to your Bitbucket Interceptor.

To use a Bitbucket Interceptor as a filter for event data, specify the event types you want the Interceptor to accept in the eventTypes field. The Interceptor accepts data event types listed in Event payload.

Below is an example Bitbucket Interceptor reference for server:

interceptors:
- ref:
    name: "bitbucket"
  params:
    - name: secretRef
      value:
        secretName: bitbucket-server-secret
        secretKey: secretToken
    - name: eventTypes
      value:
        - repo:refs_changed

For reference, below is an example legacy Bitbucket Interceptor definition:

---
apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: bitbucket-server-listener
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: bitbucket-server-triggers
      interceptors:
        - ref:
            name: "bitbucket"
          params:
            - name: secretRef
              value:
                secretName: bitbucket-server-secret
                secretKey: secretToken
            - name: eventTypes
              value:
                - repo:refs_changed
      bindings:
        - ref: bitbucket-server-binding
      template:
        ref: bitbucket-server-template

Bitbucket Cloud

At the moment, Bitbucket cloud does not support validating webhook payloads using shared secrets. See the Secure Webhooks section of Bitbucket cloud docs for more information on securing your Bitbucket webhooks.

Below is an example Bitbucket Interceptor reference for cloud:

interceptors:
- ref:
    name: "bitbucket"
  params:
    - name: eventTypes
      value:
        - repo:push

For reference, below is an example legacy Bitbucket Interceptor definition:

---
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: bitbucket-cloud-listener
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: bitbucket-cloud-triggers
      interceptors:
        - ref:
            name: "bitbucket"
          params:
            - name: eventTypes
              value:
                - repo:push
      bindings:
        - ref: bitbucket-cloud-binding
      template:
        ref: bitbucket-cloud-template

Slack Interceptors

A Slack Interceptor allows you to extract fields from a slack slash command payload which are sent in the http form-data section. the Interceptor requests fields extracts the requested fields and appends them to the extensions.

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: slack-listener
  annotations:
    tekton.dev/payload-validation: "false"
spec:
  triggers:
    - name: slack-trigger
      interceptors:
        - ref:
            name: "slack"
            kind: ClusterInterceptor
          params:
            - name: requestedFields
              value: 
                - text

Note: payload-validation must be disabled by add adding the following annotation

  annotations:
    tekton.dev/payload-validation: "false"

CEL Interceptors

A CEL Interceptor allows you to filter and modify the payloads of incoming events using the CEL expression language.

CEL Interceptors support overlays, which are CEL expressions that Tekton Triggers adds to the event payload in the top-level extensions field. overlays are accessible from TriggerBindings.

In the example overlays definition below, the Interceptor adds two new fields to the event payload that the corresponding TriggerBinding will receive in addition to the standard header and body fields: extensions.truncated_sha and extensions.branch_name:

  triggers:
    - name: cel-trig
      interceptors:
        - ref:
            name: cel
          params:
          - name: "overlays"
            value:
            - key: truncated_sha
              expression: "body.pull_request.head.sha.truncate(7)"
            - key: branch_name
              expression: "body.ref.split('/')[2]"

Below is the same example as a legacy Interceptor:

  triggers:
    - name: cel-trig
      interceptors:
        - cel:
            overlays:
            - key: truncated_sha
              expression: "body.pull_request.head.sha.truncate(7)"
            - key: branch_name
              expression: "body.ref.split('/')[2]"

You can use the key element within the overlays definition to create new or replace existing elements within the extensions field. This does not modify the body of the event payload, but instead adds the extra fields to the top-level extensions field.

For example, the following expression:

- key: short_sha
  expression: "truncate(body.pull_request.head.sha, 7)"

can access the short_sha field and its value that have been created in extensions field:

{
  "body": {
    "ref": "refs/heads/master",
    "pull_request": {
      "head": {
        "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246"
      }
    }
  },
  "extensions": {
    "short_sha": "6113728"
  }
}

Note: You can also replace existing fields by specifying a key that matches the path to an existing field/value pair.

You can access the extra fields added by a CEL Interceptor from your TriggerBinding as follows:

apiVersion: triggers.tekton.dev/v1alpha1
kind: TriggerBinding
metadata:
  name: pipeline-binding-with-cel-extensions
spec:
  params:
  - name: gitrevision
    value: $(extensions.short_sha)
  - name: branch
    value: $(extensions.branch_name)

In the example CEL Interceptor definition below, the cel-trig-with-matches Trigger filters events that don’t have an 'X-GitHub-Event' header matching 'pull_request' and adds an extra key to the JSON body of the payload with a truncated string derived from the hook body:

  triggers:
    - name: cel-trig-with-matches
      interceptors:
        - ref:
            name: "cel"
          params:
          - name: "filter"
            value: "header.match('X-GitHub-Event', 'pull_request')"
          - name: "overlays"
            value:
              - key: truncated_sha
                expression: "body.pull_request.head.sha.truncate(7)"
      bindings:
      - name: sha
        value: $(extensions.truncated_sha)

Below is the same example as a legacy Interceptor:

  triggers:
    - name: cel-trig-with-matches
      interceptors:
        - cel:
            filter: "header.match('X-GitHub-Event', 'pull_request')"
            overlays:
            - key: truncated_sha
              expression: "body.pull_request.head.sha.truncate(7)"
      bindings:
      - name: sha
        value: $(extensions.truncated_sha)

In the example CEL Interceptor definition below, the filter expression must return a true value for this Trigger to execute and apply the specified overlays:

You also have the option to omit the filter expression entirely, in which case the Interceptor applies the specified overlays to the payload’s body:

apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: cel-eventlistener-no-filter
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: cel-trig
      interceptors:
        - ref:
            name: "cel"
          params:
            - name: "overlays"
              value:
                - key: extensions.truncated_sha
                  expression: "body.pull_request.head.sha.truncate(7)"
      bindings:
      - ref: pipeline-binding
      template:
        ref: pipeline-template

Chaining `Interceptors`

You can chain Interceptors with the following constraints:

ClusterInterceptors do not modify the body of the event payload; instead, they add extra fields to the top-level extensions field.
Webhook Interceptors can modify the body of the event payload, but cannot access the top-level extensions field.

Chaining ClusterInterceptors

Each ClusterInterceptor can return values in the InterceptorResponse within the extensions field. These values are then added to the extensions field of the InterceptorRequest that is sent to the next interceptor in the chain.

If two interceptors return an extensions field with the same name, the latter one will overwrite the one from the previous one i.e. if interceptors A and B both return foo in the Extensions field of the InterceptorResponse, the values written by B will overwrite the ones written by A. To prevent this, it is recommended that each cluster interceptor write to its own top level field i.e A returns A.foo and B return B.foo in the InterceptorResponse.

Chaining Webhook Interceptors

Note: We are working on changing the behavior of Webhook Interceptors to match that of CEL Interceptors so that both Interceptor types can share data via the top-level extensions field.

Since Webhook Interceptors cannot access the extensions field, the EventListener adds the extensions field to the body of the event payload before passing it to any Webhook Interceptor. In the example Interceptor chain shown below, the first CEL Interceptor adds the truncated_sha field to the extensions field and the EventListener adds it to the body of the payload so that the Webhook Interceptor can access that data:

  interceptors:
    - cel:
        overlays:
          - key: "truncated_sha"
            expression: "body.sha.truncate(5)"
    - webhook:
      objectRef:
        kind: Service
        name: some-interceptor
        apiVersion: v1
    - cel:
        filter: "body.extensions.truncated_sha == \"abcde\"" # Can also be extensions.truncated_sha == \"abcde\"

As a result, the body of the payload sent to the Webhook Interceptor is as follows:

{
  "sha": "abcdefghi", // Original field
  "extensions": {
     "truncated_sha": "abcde" 
  }
}

As long as the Webhook Interceptor does not modify the body of the payload, the last CEL interceptor in the chain and the target TriggerBinding can access the truncated_sha field both in the body of the payload as well as via the extra fields added to the top-level extension field, namely $(body.extensions.truncated_sha) as well as $(extensions.truncated_sha).

Implementing custom `Interceptors`

Tekton Triggers ships with the ClusterInterceptorand Interceptor Custom Resource Definition (CRD), which you can use to implement custom Interceptors. See ClusterInterceptors and NamespacedInterceptors for more information.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`Interceptors`

Tekton Triggers ships with the Interceptor Custom Resource Definition (CRD), which allows you to implement a custom namespaced-scoped Webhook-style Interceptor.

A Interceptor specifies an external Kubernetes v1 Service running custom business logic that receives the event payload from the EventListener via an HTTP request and returns a processed version of the payload along with an HTTP 200 response. The Interceptor can also halt processing if the event payload does not meet criteria you have configured as well as add extra fields that are accessible in the EventListener's top-level extensions field to other Interceptors and Interceptors chained with it and the associated TriggerBinding.

Structure of a `Interceptor`

A Interceptor definition consists of the following fields:

Required:
- apiVersion - specifies the target API version, for example triggers.tekton.dev/v1alpha1
- kind - specifies that this Kubernetes resource is a Interceptor object
- metadata - specifies data that uniquely identifies this Interceptor object, for example a name
- spec - specifies the configuration information for this Interceptor object, including:
  - [clientConfig] - specifies how a client, such as an EventListener communicates with this Interceptor object

Configuring the client of the `Interceptor`

The clientConfig field specifies the client, such as an EventListener and how it communicates with the Interceptor to exchange event payload and other data. You can configure this field in one of the following ways:

Specify the url field and as its value a URL at which the corresponding Kubernetes service listens for incoming requests from this Interceptor
Specify the service field and within it reference the corresponding Kubernetes service that’s listening for incoming requests from this Interceptor

For example:

spec:
  clientConfig:
    url: "http://interceptor-svc.default.svc/"
---
spec:
  clientConfig:
    service:
      name: "my-interceptor-svc"
      namespace: "default"
      path: "/optional-path" # optional
      port: 8081 # defaults to 80

Configuring a Kubernetes Service for the `Interceptor`

The Kubernetes object running the custom business logic for your Interceptor must meet the following criteria:

Fronted by a regular Kubernetes v1 Service listening on an HTTP port (default port is 80)
Accepts an HTTP POST request that contains an InterceptorRequest as a JSON body
Returns an HTTP 200 OK response that contains an InterceptorResponse as a JSON body. If the trigger processing should continue, the interceptor should set the continue field in the response to true. If the processing should be stopped, the interceptor should set the continue field to false and also provide additional information detailing the error in the status field.
Returns a response other than HTTP 200 OK only if payload processing halts due to a catastrophic failure.

Running Interceptor as HTTPS

Triggers support writing custom interceptor for both http and https. Support of http for custom interceptor will be removed in future and only https will be supported.

End user who write https custom interceptor need to pass caBundle as well as label

  labels:
    server/type: https

to Interceptor in order to make secure connection with eventlistener.

Here is the reference for writing https server for custom interceptor.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

CEL expression extensions

The CEL expression is configured to expose parts of the request, and some custom functions to make matching easier.

In addition to the custom function extension listed below, you can craft any valid CEL expression as defined by the cel-spec language definition

String functions

The upstream CEL implementation provides extensions to the CEL specification for manipulating strings.

For example:

'refs/heads/main'.split('/') // result = list ['refs', 'heads', 'main']
['refs', 'heads', 'main'].join('/') // result = string 'refs/heads/main'
'my place'.replace('my ',' ') // result = string 'place'
'this that another'.replace('th ',' ', 2) // result = 'is at another'

The replace overload allows an optional limit on replacements.

Notes on numbers in CEL expressions

One thing to be aware of is how numeric values are treated in CEL expressions, JSON numbers are decoded to CEL double values.

For example:

{
  "count": 2,
  "measure": 1.7
}

In the JSON above, both numbers are parsed as CEL double (Go float64) values.

This means that if you want to do integer arithmetic, you’ll need to use explicit conversion functions.

From the CEL specification:

Note that currently there are no automatic arithmetic conversions for the numeric types (int, uint, and double).

You can either explicitly convert the number, or add another double value e.g.

interceptors:
  - ref:
      name: cel
      params:
      - name: overlays
        value:
        - key: count_plus_1
          expression: "body.count + 1.0"
        - key: count_plus_2
          expression: "int(body.count) + 2"
        - key: measure_times_3
          expression: "body.measure * 3.0"

These will be serialised back to JSON appropriately:

{
  "count_plus_1": 2,
  "count_plus_2": 3,
  "measure_times_3": 5.1
}

Error messages in conversions

The following example will generate an error with the JSON example.

interceptors:
  - ref:
      name: cel
      params:
      - name: overlays
        value:
          - key: bad_measure_times_3
            expression: "body.measure * 3"

bad_measure_times_3 will fail with failed to evaluate overlay expression 'body.measure * 3': no such overload because there’s no automatic conversion.

CEL expression examples

Matching on an element in an array.

CEL provides several macros which can operate on JSON objects.

If you have a JSON body like this:

{
  "labels": [
    {
      "name": "test-a"
    },
    {
      "name":"test-b"
    }
  ]
}

You can use this in filters in the following ways:

filter: body.labels.exists(x, x.name == 'test-b') is true
filter: body.labels.exists(x, x.name == 'test-c') is false
filter: body.labels.exists_one(x, x.name.endsWith('-b')) is true
filter: body.labels.exists_one(x, x.name.startsWith('test-')) is false
filter: body.labels.all(x, x.name.startsWith('test-')) is true
filter: body.labels.all(x, x.name.endsWith('-b')) is false

You can also parse additional data from each of the labels:

- name: overlays
  value:
  - key: suffixes
    expression: "body.labels.map(x, x.name.substring(x.name.lastIndexOf('-')+1))"

This yields an array of ["a", "b"] in the suffixes extension key.

- name: overlays
  value:
  - key: filtered
    expression: "body.labels.filter(x, x.name.endsWith('-b'))"

This would add an extensions key filtered with only one of the labels.

[
  {
    "name": "test-b"
  }
]

cel-go extensions

All the functionality from the cel-go project’s CEL extension is available in your CEL expressions.

The following extensions are available:

cel-go Bytes

The cel-go project function base64.decode returns a CEL Bytes value.

To compare this to a string, you will need to convert it to a Bytes type:

base64.decode(body.b64value) == b'hello' # compare to Bytes literal
base64.decode(body.b64value) == bytes('hello') # convert to bytes.

Returning Bytes

If you decode a base64 string with the cel-go base64 decoder, the result will be a set of base64 decoded bytes. To ensure the result is encoded as a string you will need to explicitly convert it to a CEL string.

interceptors:
  - ref:
      name: "cel"
    params:
      - name: "overlays"
        value:
        - key: base64_decoded
          expression: "string(base64.decode(body.b64Value))"

This will correctly appear in the extension as the decoded version.

List of extensions

The body from the http.Request value is decoded to JSON and exposed, and the headers are also available.

Symbol	Type	Description	Example
body	map(string, dynamic)	This is the decoded JSON body from the incoming http.Request exposed as a map of string keys to any value types.	body.value == 'test'
header	map(string, list(string))	This is the request Header.	header['X-Test'][0] == 'test-value'
requestURL	string	This is the URL for the incoming HTTP request.	requestURL.parseURL().path

NOTE: The header value is a Go http.Header, which is defined as:

type Header map[string][]string

i.e. the header is a mapping of strings, to arrays of strings, see the match function on headers below for an extension that makes looking up headers easier.

List of extension functions

This lists custom functions that can be used from CEL expressions in the CEL interceptor.

Symbol

Type

Description

Example

match

header.match(string, string) -> bool

Uses the canonical header matching from Go's http.Request to match the header against the value.

header.match('x-test', 'test-value')

canonical

header.canonical(string) -> string

Uses the canonical header matching from Go's http.Request to get the provided header name.

header.canonical('x-test')

truncate

<string>.truncate(uint) -> string

Truncates a string to no more than the specified length.

body.commit.sha.truncate(5)

split

<string>.split(string) -> list(string)

Splits a string on the provided separator value.

body.ref.split('/')

join

<list(string)>.join(string) -> string

Joins a list of strings on the provided separator value.

['body', 'refs', 'main'].join('/')

decodeb64 deprecated: please use base64.decode

<string>.decodeb64() -> string

Decodes a base64 encoded string.

body.message.data.decodeb64()

compareSecret

<string>.compareSecret(string, string, string) -> bool

Constant-time comparison of strings against secrets, this will fetch the secret using the combination of namespace/name and compare the token key to the string using a cryptographic constant-time comparison..

The event-listener service account must have access to the secret. The parameters to the function are 1. the key within the secret, 2. the secret name, and 3. the namespace for the secret (optional, defaults to the namespace of the EventListener).

header.canonical('X-Secret-Token').compareSecret('', 'secret-name', 'namespace')

compareSecret

<string>.compareSecret(string, string) -> bool

This is almost identical to the version above, but only requires two arguments, the namespace is assumed to be the namespace for the event-listener.

header.canonical('X-Secret-Token').compareSecret('key', 'secret-name')

parseJSON()

<string>.parseJSON() -> map<string, dyn>

This parses a string that contains a JSON body into a map which which can be subsequently used in other expressions.

'{"testing":"value"}'.parseJSON().testing == "value"

parseYAML()

<string>.parseYAML() -> map<string, dyn>

This parses a string that contains a YAML body into a map which which can be subsequently used in other expressions.

'key1: value1\nkey2: value2\n'.parseYAML().key1 == "value"

parseURL()

<string>.parseURL() -> map<string, dyn>

This parses a string that contains a URL into a map with keys for the elements of the URL.
The resulting map will contain the following keys for this URL "https://user:pass@example.com/test/path?s=testing#first"

Field	Example
scheme	https
host	example.com
path	/test/path
rawQuery	s=testing
fragment	first
query	{"s": "testing"}
queryStrings	{"s": ["testing"]}
auth	{"username": "user", "password": "pass"}

Note the difference between query and queryStrings, in query, multiple query params with the same name would be comma separated, for the case where a single string is provided, this will just be the single string value. For queryString the query param values are provided as a list, which can be accessed by indexing.

'https://example.com/test?query=testing'.parseURL().query['query'] == "testing"

marshalJSON()

<jsonObjectOrList>.marshalJSON() -> <string>

Returns the JSON encoding of 'jsonObjectOrList' as a string.

{"testing":"value"}.marshalJSON() == "{\"testing\": \"value\"}"

first()

<jsonArray>.first() -> <jsonObject>

Returns the first element in the array.

[1, 2, 3, 4, 5].first() == 1

last()

<jsonArray>.last() -> <jsonObject>

Returns the last element in the array.

[1, 2, 3, 4, 5].last() == 5

translate()

<string>.translate(string, string) -> <string>

Uses a regular expression to replace characters from the source string with characters from the replacements.

"This is $an Invalid5String ".translate("[^a-z0-9]+", "") == "hisisannvalid5tring"

"This is $an Invalid5String ".translate("[^a-z0-9]+", "ABC") == "ABChisABCisABCanABCnvalid5ABCtring"

lowerAscii()

<string>.lowerAscii() -> <string>

Returns a new string where all ASCII characters are lower-cased.

"TacoCat".lowerAscii() == "tacocat"

"TacoCÆt Xii".lowerAscii() == "tacocÆt xii"

upperAscii()

<string>.upperAscii() -> <string>

Returns a new string where all ASCII characters are upper-cased.

"TacoCat".upperAscii() == "TACOCAT"

"TacoCÆt Xii".upperAscii() == "TACOCÆT XII"

Troubleshooting CEL expressions

You can use the cel-eval tool to evaluate your CEL expressions against a specific HTTP request.

To install the cel-eval tool use the following command:

$ go install github.com/tektoncd/triggers/cmd/cel-eval@latest

Below is an example of using the tool to evaluate a CEL expression:

$ cat testdata/expression.txt
body.test.nested == "value"

$ cat testdata/http.txt
POST /foo HTTP/1.1
Content-Length: 29
Content-Type: application/json
X-Header: tacocat

{"test": {"nested": "value"}}

$ cel-eval -e testdata/expression.txt -r testdata/http.txt
true

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

`Triggers`

A Trigger specifies what happens when the EventListener detects an event. A Trigger specifies a TriggerTemplate, a TriggerBinding, and optionally an Interceptor.

Structure of a `Trigger`

When creating a Trigger definition you must specify the required fields and can also specify any of the optional fields listed below:

Required:
- apiVersion - Specifies the API version; for example triggers.tekton.dev/v1alpha1.
- kind - Specifies that this resource object is a Trigger object.
- metadata - Specifies metadata to uniquely identify this Trigger object; for example a name.
- spec - Specifies the configuration information for this Trigger object, including:
  - [bindings] - (Optional) Specifies a list of field bindings; each binding can either reference an existing TriggerBinding or embedded a TriggerBinding definition using a name/value pair.
  - [template] - Specifies the corresponding TriggerTemplate either as a reference as an embedded TriggerTemplate definition.
  - [interceptors] - (Optional) specifies one or more Interceptors that will process the payload data before passing it to the TriggerTemplate.
  - ref - a reference to a ClusterInterceptor or Interceptor object with the following fields:
    - name - the name of the referenced ClusterInterceptor
    - kind - (Optional) specifies that whether the referenced Kubernetes object is a ClusterInterceptor object or NamespacedInterceptor. Default value is ClusterInterceptor
  - [serviceAccountName] - (Optional) Specifies the ServiceAccount to supply to the EventListener to instantiate/execute the target resources.

Below is an example Trigger definition:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: trigger
spec:
  interceptors:
    - ref:
        name: "cel"
      params:
        - name: "filter"
          value: "header.match('X-GitHub-Event', 'pull_request')"
        - name: "overlays"
          value:
            - key: extensions.truncated_sha
              expression: "body.pull_request.head.sha.truncate(7)"
  bindings:
  - ref: pipeline-binding
  template:
    ref: pipeline-template

Specifying the corresponding `TriggerTemplate`

In the template field, you can do one of the following:

Use the name parameter to reference an external TriggerTemplate object, or
Use the spec parameter to directly embed a TriggerTemplate definition.

For example:

# Example: embedded TriggerTemplate definition
triggers:
  - name: "my-trigger"
    template:
      spec: 
        params:
          - name: "my-param-name"
        resourcetemplates:
        - apiVersion: "tekton.dev/v1beta1"
          kind: TaskRun
          metadata:
            generateName: "pr-run-"
          spec:
            taskSpec:
              steps:
              - image: ubuntu
                script: echo "hello there"

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Events in Tekton Triggers

Triggers event controller emits Kubernetes events when EventListener get request to process Triggers. This allows you to monitor and react to what’s happening during execution by retrieving those events using the kubectl get events command.

Events in `EventListener`

EventListener emit events for the following Reasons:

Started: emitted the first time when the EventListener received request.
Succeeded: emitted when eventlistener received request and process all triggers request.
Done: emitted when its done with eventlistener handler.
Failed: emitted if triggers failed to process the request.

Events format

Resource	Event	Event Type
`EventListener`	`Started`	`dev.tekton.event.triggers.started.v1`
`EventListener`	`Succeed`	`dev.tekton.event.triggers.successful.v1`
`EventListener`	`Done`	`dev.tekton.event.triggers.done.v1`
`EventListener`	`Failed`	`dev.tekton.event.triggers.failed.v1`

Note

By default Kubernetes events are disabled for EventListener.

To enable Kubernetes events add/update controller.yaml with below arg

    spec:
      serviceAccountName: tekton-triggers-controller
      containers:
      - name: tekton-triggers-controller
        image: "ko://github.com/tektoncd/triggers/cmd/controller"
        args: [
          "-el-events", "enable",

Default value is disable.

To view the events execute below command

kubectl get events

Vault: Triggers API

Mon, 01 Jan 0001 00:00:00 +0000

Packages:

triggers.tekton.dev/v1alpha1

Package v1alpha1 contains API Schema definitions for the triggers v1alpha1 API group

Resource Types:

ClusterTriggerBinding

ClusterTriggerBinding is a TriggerBinding with a cluster scope. ClusterTriggerBindings are used to represent TriggerBindings that should be publicly addressable from any namespace in the cluster.

Field Description

apiVersion
string triggers.tekton.dev/v1alpha1

kind
string ClusterTriggerBinding

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerBindingSpec

(Optional)

Spec holds the desired state of the ClusterTriggerBinding from the client

params
[]Param

Params defines the parameter mapping from the given input event.

status
TriggerBindingStatus (Optional)

EventListener

EventListener exposes a service to accept HTTP event payloads.

Field Description

apiVersion
string triggers.tekton.dev/v1alpha1

kind
string EventListener

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
EventListenerSpec

(Optional)

Spec holds the desired state of the EventListener from the client

`serviceAccountName` string
`triggers` []EventListenerTrigger
`namespaceSelector` NamespaceSelector
`labelSelector` Kubernetes meta/v1.LabelSelector
`resources` Resources

status
EventListenerStatus (Optional)

Trigger

Trigger defines a mapping of an input event to parameters. This is used to extract information from events to be passed to TriggerTemplates within a Trigger.

Field Description

apiVersion
string triggers.tekton.dev/v1alpha1

kind
string Trigger

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerSpec

(Optional)

Spec holds the desired state of the Trigger

`bindings` []TriggerSpecBinding
`template` TriggerSpecTemplate
`name` string	(Optional)
`interceptors` []TriggerInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; Unlike EventListeners, this should be scoped to the same namespace as the Trigger itself

TriggerBinding

TriggerBinding defines a mapping of an input event to parameters. This is used to extract information from events to be passed to TriggerTemplates within a Trigger.

Field Description

apiVersion
string triggers.tekton.dev/v1alpha1

kind
string TriggerBinding

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerBindingSpec

(Optional)

Spec holds the desired state of the TriggerBinding

params
[]Param

Params defines the parameter mapping from the given input event.

status
TriggerBindingStatus (Optional)

TriggerTemplate

TriggerTemplate takes parameters and uses them to create CRDs

Field Description

apiVersion
string triggers.tekton.dev/v1alpha1

kind
string TriggerTemplate

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerTemplateSpec

(Optional)

Spec holds the desired state of the TriggerTemplate from the client

`params` []ParamSpec
`resourcetemplates` []TriggerResourceTemplate

status
TriggerTemplateStatus (Optional)

BitbucketInterceptor

(Appears on:TriggerInterceptor)

BitbucketInterceptor provides a webhook to intercept and pre-process events

Field	Description
`secretRef` SecretRef
`eventTypes` []string

CELInterceptor

(Appears on:TriggerInterceptor)

CELInterceptor provides a webhook to intercept and pre-process events

Field	Description
`filter` string
`overlays` []CELOverlay

CELOverlay

(Appears on:CELInterceptor)

CELOverlay provides a way to modify the request body using DeprecatedCEL expressions

Field	Description
`key` string
`expression` string

ClientConfig

(Appears on:ClusterInterceptorSpec, InterceptorSpec)

ClientConfig describes how a client can communicate with the Interceptor

Field	Description
`caBundle` []byte	CaBundle is a PEM encoded CA bundle which will be used to validate the clusterinterceptor server certificate
`url` knative.dev/pkg/apis.URL	URL is a fully formed URL pointing to the interceptor Mutually exclusive with Service
`service` ServiceReference	Service is a reference to a Service object where the interceptor is running Mutually exclusive with URL

ClusterInterceptor

ClusterInterceptor describes a pluggable interceptor including configuration such as the fields it accepts and its deployment address. The type is based on the Validating/MutatingWebhookConfiguration types for configuring AdmissionWebhooks

Field Description

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
ClusterInterceptorSpec

clientConfig
ClientConfig

status
ClusterInterceptorStatus (Optional)

ClusterInterceptorSpec

(Appears on:ClusterInterceptor)

ClusterInterceptorSpec describes the Spec for an ClusterInterceptor

Field	Description
`clientConfig` ClientConfig

ClusterInterceptorStatus

(Appears on:ClusterInterceptor)

ClusterInterceptorStatus holds the status of the ClusterInterceptor

Field Description

Field	Description
`Status` knative.dev/pkg/apis/duck/v1.Status	(Members of `Status` are embedded into this type.)
`AddressStatus` knative.dev/pkg/apis/duck/v1.AddressStatus	(Members of `AddressStatus` are embedded into this type.) ClusterInterceptor is Addressable and exposes the URL where the Interceptor is running

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

AddressStatus
knative.dev/pkg/apis/duck/v1.AddressStatus

(Members of AddressStatus are embedded into this type.)

ClusterInterceptor is Addressable and exposes the URL where the Interceptor is running

CustomResource

(Appears on:Resources)

Field	Description
`RawExtension` k8s.io/apimachinery/pkg/runtime.RawExtension	(Members of `RawExtension` are embedded into this type.)

EventInterceptor

(Appears on:EventListenerTrigger)

EventInterceptor provides a hook to intercept and pre-process events

EventListenerBinding

(Appears on:EventListenerTrigger)

EventListenerBinding refers to a particular TriggerBinding or ClusterTriggerBindingresource.

EventListenerConfig

(Appears on:EventListenerStatus)

EventListenerConfig stores configuration for resources generated by the EventListener

Field	Description
`generatedName` string	GeneratedResourceName is the name given to all resources reconciled by the EventListener

EventListenerSpec

(Appears on:EventListener)

EventListenerSpec defines the desired state of the EventListener, represented by a list of Triggers.

Field	Description
`serviceAccountName` string
`triggers` []EventListenerTrigger
`namespaceSelector` NamespaceSelector
`labelSelector` Kubernetes meta/v1.LabelSelector
`resources` Resources

EventListenerStatus

(Appears on:EventListener)

EventListenerStatus holds the status of the EventListener

Field Description

Field	Description
`Status` knative.dev/pkg/apis/duck/v1.Status	(Members of `Status` are embedded into this type.)
`AddressStatus` knative.dev/pkg/apis/duck/v1alpha1.AddressStatus	(Members of `AddressStatus` are embedded into this type.) EventListener is Addressable. It currently exposes the service DNS address of the the EventListener sink
`configuration` EventListenerConfig	Configuration stores configuration for the EventListener service

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

AddressStatus
knative.dev/pkg/apis/duck/v1alpha1.AddressStatus

(Members of AddressStatus are embedded into this type.)

EventListener is Addressable. It currently exposes the service DNS address of the the EventListener sink

configuration
EventListenerConfig

Configuration stores configuration for the EventListener service

EventListenerTemplate

(Appears on:EventListenerTrigger)

EventListenerTemplate refers to a particular TriggerTemplate resource.

EventListenerTrigger

(Appears on:EventListenerSpec)

EventListenerTrigger represents a connection between TriggerBinding, Params, and TriggerTemplate; TriggerBinding provides extracted values for TriggerTemplate to then create resources from. TriggerRef can also be provided instead of TriggerBinding, Interceptors and TriggerTemplate

Field	Description
`bindings` []EventListenerBinding
`template` EventListenerTemplate
`triggerRef` string
`name` string	(Optional)
`interceptors` []EventInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; more granular authorization for who is allowed to utilize the associated pipeline vs. defaulting to whatever permissions are associated with the entire EventListener and associated sink facilitates multi-tenant model based scenarios

GitHubInterceptor

(Appears on:TriggerInterceptor)

GitHubInterceptor provides a webhook to intercept and pre-process events

Field	Description
`secretRef` SecretRef
`eventTypes` []string

GitLabInterceptor

(Appears on:TriggerInterceptor)

GitLabInterceptor provides a webhook to intercept and pre-process events

Field	Description
`secretRef` SecretRef
`eventTypes` []string

Interceptor

Interceptor describes a pluggable interceptor including configuration such as the fields it accepts and its deployment address. The type is based on the Validating/MutatingWebhookConfiguration types for configuring AdmissionWebhooks

Field Description

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
InterceptorSpec

clientConfig
ClientConfig

status
InterceptorStatus (Optional)

InterceptorInterface

InterceptorKind (`string` alias)

(Appears on:InterceptorRef)

InterceptorKind defines the type of Interceptor used by the Trigger.

Value	Description
"ClusterInterceptor"	ClusterInterceptorKind indicates that Interceptor type has a cluster scope.
"NamespacedInterceptor"	NamespacedInterceptorKind indicated that interceptor has a namespaced scope

InterceptorParams

(Appears on:TriggerInterceptor)

InterceptorParams defines a key-value pair that can be passed on an interceptor

Field	Description
`name` string
`value` k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1.JSON

InterceptorRef

(Appears on:TriggerInterceptor)

InterceptorRef provides a Reference to a ClusterInterceptor

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`kind` InterceptorKind	(Optional) InterceptorKind indicates the kind of the Interceptor, namespaced or cluster scoped.
`apiVersion` string	(Optional) API version of the referent

InterceptorRequest

Do not generate DeepCopy(). See #827

Field	Description
`body` string	Body is the incoming HTTP event body. We use a “string” representation of the JSON body in order to preserve the body exactly as it was sent (including spaces etc.). This is necessary for some interceptors e.g. GitHub for validating the body with a signature. While []byte can also store an exact representation of the body, `json.Marshal` will compact []byte to a base64 encoded string which means that we will lose the spaces any time we marshal this struct.
`header` map[string][]string	Header are the headers for the incoming HTTP event
`extensions` map[string]interface{}	Extensions are extra values that are added by previous interceptors in a chain
`interceptor_params` map[string]interface{}	InterceptorParams are the user specified params for interceptor in the Trigger
`context` TriggerContext	Context contains additional metadata about the event being processed

InterceptorResponse

Do not generate Deepcopy(). See #827

Field	Description
`extensions` map[string]interface{}	Extensions are additional fields that is added to the interceptor event.
`continue` bool	Continue indicates if the EventListener should continue processing the Trigger or not
`status` Status	Status is an Error status containing details on any interceptor processing errors

InterceptorSpec

(Appears on:Interceptor)

InterceptorSpec describes the Spec for an Interceptor

Field	Description
`clientConfig` ClientConfig

InterceptorStatus

(Appears on:Interceptor)

InterceptorStatus holds the status of the Interceptor

Field Description

Field	Description
`Status` knative.dev/pkg/apis/duck/v1.Status	(Members of `Status` are embedded into this type.)
`AddressStatus` knative.dev/pkg/apis/duck/v1.AddressStatus	(Members of `AddressStatus` are embedded into this type.) Interceptor is Addressable and exposes the URL where the Interceptor is running

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

AddressStatus
knative.dev/pkg/apis/duck/v1.AddressStatus

(Members of AddressStatus are embedded into this type.)

Interceptor is Addressable and exposes the URL where the Interceptor is running

KubernetesResource

(Appears on:Resources)

Field Description

replicas
int32

serviceType
Kubernetes core/v1.ServiceType

spec
knative.dev/pkg/apis/duck/v1.WithPodSpec

template
knative.dev/pkg/apis/duck/v1.PodSpecable

NamespaceSelector

(Appears on:EventListenerSpec)

NamespaceSelector is a selector for selecting either all namespaces or a list of namespaces.

Field	Description
`matchNames` []string	List of namespace names.

Param

(Appears on:TriggerBindingSpec)

Param defines a string value to be used for a ParamSpec with the same name.

Field	Description
`name` string
`value` string

ParamSpec

(Appears on:TriggerTemplateSpec)

ParamSpec defines an arbitrary named input whose value can be supplied by a Param.

Field	Description
`name` string	Name declares the name by which a parameter is referenced.
`description` string	(Optional) Description is a user-facing description of the parameter that may be used to populate a UI.
`default` string	(Optional) Default is the value a parameter takes if no input value via a Param is supplied.

Resources

(Appears on:EventListenerSpec)

Field	Description
`kubernetesResource` KubernetesResource
`customResource` CustomResource

SecretRef

(Appears on:BitbucketInterceptor, GitHubInterceptor, GitLabInterceptor)

SecretRef contains the information required to reference a single secret string This is needed because the other secretRef types are not cross-namespace and do not actually contain the “SecretName” field, which allows us to access a single secret value.

Field	Description
`secretKey` string
`secretName` string

ServiceReference

(Appears on:ClientConfig)

ServiceReference is a reference to a Service object with an optional path

Field	Description
`name` string	Name is the name of the service
`namespace` string	Namespace is the namespace of the service
`path` string	(Optional) Path is an optional URL path
`port` int32	Port is a valid port number

Status

(Appears on:InterceptorResponse, StatusError)

Field	Description
`code` google.golang.org/grpc/codes.Code	The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
`message` string	A developer-facing error message, which should be in English.

StatusError

Field	Description
`s` Status

TriggerBindingInterface

TriggerBindingInterface is implemented by TriggerBinding and ClusterTriggerBinding

TriggerBindingKind (`string` alias)

(Appears on:TriggerSpecBinding)

Check that EventListener may be validated and defaulted. TriggerBindingKind defines the type of TriggerBinding used by the EventListener.

Value	Description
"ClusterTriggerBinding"	ClusterTriggerBindingKind indicates that triggerbinding type has a cluster scope.
"TriggerBinding"	NamespacedTriggerBindingKind indicates that triggerbinding type has a namespace scope.

TriggerBindingSpec

(Appears on:ClusterTriggerBinding, TriggerBinding)

TriggerBindingSpec defines the desired state of the TriggerBinding.

Field	Description
`params` []Param	Params defines the parameter mapping from the given input event.

TriggerBindingStatus

(Appears on:ClusterTriggerBinding, TriggerBinding)

TriggerBindingStatus defines the observed state of TriggerBinding.

TriggerContext

(Appears on:InterceptorRequest)

Field	Description
`event_url` string	EventURL is the URL of the incoming event
`event_id` string	EventID is a unique ID assigned by Triggers to each event
`trigger_id` string	TriggerID is of the form namespace/$ns/triggers/$name

TriggerInterceptor

(Appears on:TriggerSpec)

TriggerInterceptor provides a hook to intercept and pre-process events

Field	Description
`name` string	Optional name to identify the current interceptor configuration
`ref` InterceptorRef	Ref refers to the Interceptor to use
`params` []InterceptorParams	Params are the params to send to the interceptor
`webhook` WebhookInterceptor	WebhookInterceptor refers to an old style webhook interceptor service
`github` GitHubInterceptor	Deprecated old fields below
`gitlab` GitLabInterceptor
`cel` CELInterceptor
`bitbucket` BitbucketInterceptor

TriggerResourceTemplate

(Appears on:TriggerTemplateSpec)

TriggerResourceTemplate describes a resource to create

Field	Description
`RawExtension` k8s.io/apimachinery/pkg/runtime.RawExtension	(Members of `RawExtension` are embedded into this type.)

TriggerSpec

(Appears on:Trigger)

TriggerSpec represents a connection between TriggerSpecBinding, and TriggerSpecTemplate; TriggerSpecBinding provides extracted values for TriggerSpecTemplate to then create resources from.

Field	Description
`bindings` []TriggerSpecBinding
`template` TriggerSpecTemplate
`name` string	(Optional)
`interceptors` []TriggerInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; Unlike EventListeners, this should be scoped to the same namespace as the Trigger itself

TriggerSpecBinding

(Appears on:TriggerSpec)

Field	Description
`name` string	Name is the name of the binding param Mutually exclusive with Ref
`value` string	Value is the value of the binding param. Can contain JSONPath Has to be pointer since “” is a valid value Required if Name is also specified.
`ref` string	Ref is a reference to a TriggerBinding kind. Mutually exclusive with Name
`kind` TriggerBindingKind	Kind can only be provided if Ref is also provided. Defaults to TriggerBinding
`apiversion` string	APIVersion of the binding ref

TriggerSpecTemplate

(Appears on:TriggerSpec)

Field Description

ref
string

apiversion
string

spec
TriggerTemplateSpec

TriggerTemplateSpec

(Appears on:TriggerTemplate, TriggerSpecTemplate)

TriggerTemplateSpec holds the desired state of TriggerTemplate

Field	Description
`params` []ParamSpec
`resourcetemplates` []TriggerResourceTemplate

TriggerTemplateStatus

(Appears on:TriggerTemplate)

TriggerTemplateStatus describes the desired state of TriggerTemplate

WebhookInterceptor

(Appears on:TriggerInterceptor)

WebhookInterceptor provides a webhook to intercept and pre-process events

Field	Description
`objectRef` Kubernetes core/v1.ObjectReference	(Optional) ObjectRef is a reference to an object that will resolve to a cluster DNS name to use as the EventInterceptor. Either objectRef or url can be specified
`url` knative.dev/pkg/apis.URL	(Optional)
`header` []github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param	Header is a group of key-value pairs that can be appended to the interceptor request headers. This allows the interceptor to make decisions specific to an EventListenerTrigger.

triggers.tekton.dev/v1beta1

package v1beta1 contains API Schema definitions for the triggers v1beta1 API group

Resource Types:

ClusterTriggerBinding

ClusterTriggerBinding is a TriggerBinding with a cluster scope. ClusterTriggerBindings are used to represent TriggerBindings that should be publicly addressable from any namespace in the cluster.

Field Description

apiVersion
string triggers.tekton.dev/v1beta1

kind
string ClusterTriggerBinding

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerBindingSpec

(Optional)

Spec holds the desired state of the ClusterTriggerBinding from the client

params
[]Param

Params defines the parameter mapping from the given input event.

status
TriggerBindingStatus (Optional)

EventListener

EventListener exposes a service to accept HTTP event payloads.

Field Description

apiVersion
string triggers.tekton.dev/v1beta1

kind
string EventListener

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
EventListenerSpec

(Optional)

Spec holds the desired state of the EventListener from the client

`serviceAccountName` string
`triggers` []EventListenerTrigger
`triggerGroups` []EventListenerTriggerGroup	Trigger groups allow for centralized processing of an interceptor chain
`namespaceSelector` NamespaceSelector
`labelSelector` Kubernetes meta/v1.LabelSelector
`resources` Resources
`cloudEventURI` string

status
EventListenerStatus (Optional)

Trigger

Trigger defines a mapping of an input event to parameters. This is used to extract information from events to be passed to TriggerTemplates within a Trigger.

Field Description

apiVersion
string triggers.tekton.dev/v1beta1

kind
string Trigger

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerSpec

(Optional)

Spec holds the desired state of the Trigger

`bindings` []TriggerSpecBinding
`template` TriggerSpecTemplate
`name` string	(Optional)
`interceptors` []TriggerInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; Unlike EventListeners, this should be scoped to the same namespace as the Trigger itself

TriggerBinding

TriggerBinding defines a mapping of an input event to parameters. This is used to extract information from events to be passed to TriggerTemplates within a Trigger.

Field Description

apiVersion
string triggers.tekton.dev/v1beta1

kind
string TriggerBinding

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerBindingSpec

(Optional)

Spec holds the desired state of the TriggerBinding

params
[]Param

Params defines the parameter mapping from the given input event.

status
TriggerBindingStatus (Optional)

TriggerTemplate

TriggerTemplate takes parameters and uses them to create CRDs

Field Description

apiVersion
string triggers.tekton.dev/v1beta1

kind
string TriggerTemplate

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TriggerTemplateSpec

(Optional)

Spec holds the desired state of the TriggerTemplate from the client

`params` []ParamSpec
`resourcetemplates` []TriggerResourceTemplate

status
TriggerTemplateStatus (Optional)

CustomResource

(Appears on:Resources)

Field	Description
`RawExtension` k8s.io/apimachinery/pkg/runtime.RawExtension	(Members of `RawExtension` are embedded into this type.)

EventInterceptor

(Appears on:EventListenerTrigger)

EventInterceptor provides a hook to intercept and pre-process events

EventListenerBinding

(Appears on:EventListenerTrigger)

EventListenerBinding refers to a particular TriggerBinding or ClusterTriggerBinding resource.

EventListenerConfig

(Appears on:EventListenerStatus)

EventListenerConfig stores configuration for resources generated by the EventListener

Field	Description
`generatedName` string	GeneratedResourceName is the name given to all resources reconciled by the EventListener

EventListenerSpec

(Appears on:EventListener)

EventListenerSpec defines the desired state of the EventListener, represented by a list of Triggers.

Field	Description
`serviceAccountName` string
`triggers` []EventListenerTrigger
`triggerGroups` []EventListenerTriggerGroup	Trigger groups allow for centralized processing of an interceptor chain
`namespaceSelector` NamespaceSelector
`labelSelector` Kubernetes meta/v1.LabelSelector
`resources` Resources
`cloudEventURI` string

EventListenerStatus

(Appears on:EventListener)

EventListenerStatus holds the status of the EventListener

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

AddressStatus
knative.dev/pkg/apis/duck/v1beta1.AddressStatus

(Members of AddressStatus are embedded into this type.)

EventListener is Addressable. It currently exposes the service DNS address of the the EventListener sink

configuration
EventListenerConfig

Configuration stores configuration for the EventListener service

EventListenerTemplate

(Appears on:EventListenerTrigger)

EventListenerTemplate refers to a particular TriggerTemplate resource.

EventListenerTrigger

(Appears on:EventListenerSpec)

Field	Description
`bindings` []EventListenerBinding
`template` EventListenerTemplate
`triggerRef` string
`name` string	(Optional)
`interceptors` []EventInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; more granular authorization for who is allowed to utilize the associated pipeline vs. defaulting to whatever permissions are associated with the entire EventListener and associated sink facilitates multi-tenant model based scenarios

EventListenerTriggerGroup

(Appears on:EventListenerSpec)

EventListenerTriggerGroup defines a group of Triggers that share a common set of interceptors

Field	Description
`name` string
`interceptors` []TriggerInterceptor
`triggerSelector` EventListenerTriggerSelector

EventListenerTriggerSelector

(Appears on:EventListenerTriggerGroup)

EventListenerTriggerSelector defines ways to select a group of triggers using their metadata

Field	Description
`namespaceSelector` NamespaceSelector
`labelSelector` Kubernetes meta/v1.LabelSelector

InterceptorInterface

InterceptorKind (`string` alias)

(Appears on:InterceptorRef)

InterceptorKind defines the type of Interceptor used by the Trigger.

Value	Description
"ClusterInterceptor"	ClusterInterceptorKind indicates that Interceptor type has a cluster scope.
"NamespacedInterceptor"	NamespacedInterceptorKind indicates that Interceptor type has a namespace scope.

InterceptorParams

(Appears on:TriggerInterceptor)

InterceptorParams defines a key-value pair that can be passed on an interceptor

Field	Description
`name` string
`value` k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1.JSON

InterceptorRef

(Appears on:TriggerInterceptor)

InterceptorRef provides a Reference to a ClusterInterceptor

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`kind` InterceptorKind	(Optional) InterceptorKind indicates the kind of the Interceptor, namespaced or cluster scoped.
`apiVersion` string	(Optional) API version of the referent

InterceptorRequest

Do not generate DeepCopy(). See #827

Field	Description
`body` string	Body is the incoming HTTP event body. We use a “string” representation of the JSON body in order to preserve the body exactly as it was sent (including spaces etc.). This is necessary for some interceptors e.g. GitHub for validating the body with a signature. While []byte can also store an exact representation of the body, `json.Marshal` will compact []byte to a base64 encoded string which means that we will lose the spaces any time we marshal this struct.
`header` map[string][]string	Header are the headers for the incoming HTTP event
`extensions` map[string]interface{}	Extensions are extra values that are added by previous interceptors in a chain
`interceptor_params` map[string]interface{}	InterceptorParams are the user specified params for interceptor in the Trigger
`context` TriggerContext	Context contains additional metadata about the event being processed

InterceptorResponse

Do not generate Deepcopy(). See #827

Field	Description
`extensions` map[string]interface{}	Extensions are additional fields that is added to the interceptor event.
`continue` bool	Continue indicates if the EventListener should continue processing the Trigger or not
`status` Status	Status is an Error status containing details on any interceptor processing errors

KubernetesResource

(Appears on:Resources)

Field Description

replicas
int32

serviceType
Kubernetes core/v1.ServiceType

servicePort
int32

serviceLoadBalancerClass
string

spec
knative.dev/pkg/apis/duck/v1.WithPodSpec

template
knative.dev/pkg/apis/duck/v1.PodSpecable

NamespaceSelector

(Appears on:EventListenerSpec, EventListenerTriggerSelector)

NamespaceSelector is a selector for selecting either all namespaces or a list of namespaces.

Field	Description
`matchNames` []string	List of namespace names.

Param

(Appears on:TriggerBindingSpec)

Param defines a string value to be used for a ParamSpec with the same name.

Field	Description
`name` string
`value` string

ParamSpec

(Appears on:TriggerTemplateSpec)

ParamSpec defines an arbitrary named input whose value can be supplied by a Param.

Field	Description
`name` string	Name declares the name by which a parameter is referenced.
`description` string	(Optional) Description is a user-facing description of the parameter that may be used to populate a UI.
`default` string	(Optional) Default is the value a parameter takes if no input value via a Param is supplied.

Resources

(Appears on:EventListenerSpec)

Field	Description
`kubernetesResource` KubernetesResource
`customResource` CustomResource

SecretRef

Field	Description
`secretKey` string
`secretName` string

Status

(Appears on:InterceptorResponse, StatusError)

Field	Description
`code` google.golang.org/grpc/codes.Code	The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
`message` string	A developer-facing error message, which should be in English.

StatusError

Field	Description
`s` Status

TriggerBindingInterface

TriggerBindingInterface is implemented by TriggerBinding and ClusterTriggerBinding

TriggerBindingKind (`string` alias)

(Appears on:TriggerSpecBinding)

Check that EventListener may be validated and defaulted. TriggerBindingKind defines the type of TriggerBinding used by the EventListener.

Value	Description
"ClusterTriggerBinding"	ClusterTriggerBindingKind indicates that triggerbinding type has a cluster scope.
"TriggerBinding"	NamespacedTriggerBindingKind indicates that triggerbinding type has a namespace scope.

TriggerBindingSpec

(Appears on:ClusterTriggerBinding, TriggerBinding)

TriggerBindingSpec defines the desired state of the TriggerBinding.

Field	Description
`params` []Param	Params defines the parameter mapping from the given input event.

TriggerBindingStatus

(Appears on:ClusterTriggerBinding, TriggerBinding)

TriggerBindingStatus defines the observed state of TriggerBinding.

TriggerContext

(Appears on:InterceptorRequest)

Field	Description
`event_url` string	EventURL is the URL of the incoming event
`event_id` string	EventID is a unique ID assigned by Triggers to each event
`trigger_id` string	TriggerID is of the form namespace/$ns/triggers/$name

TriggerInterceptor

(Appears on:EventListenerTriggerGroup, TriggerSpec)

TriggerInterceptor provides a hook to intercept and pre-process events

Field	Description
`name` string	Optional name to identify the current interceptor configuration
`ref` InterceptorRef	Ref refers to the Interceptor to use
`params` []InterceptorParams	Params are the params to send to the interceptor
`webhook` WebhookInterceptor	WebhookInterceptor refers to an old style webhook interceptor service

TriggerResourceTemplate

(Appears on:TriggerTemplateSpec)

TriggerResourceTemplate describes a resource to create

Field	Description
`RawExtension` k8s.io/apimachinery/pkg/runtime.RawExtension	(Members of `RawExtension` are embedded into this type.)

TriggerSpec

(Appears on:Trigger)

TriggerSpec represents a connection between TriggerSpecBinding, and TriggerSpecTemplate; TriggerSpecBinding provides extracted values for TriggerSpecTemplate to then create resources from.

Field	Description
`bindings` []TriggerSpecBinding
`template` TriggerSpecTemplate
`name` string	(Optional)
`interceptors` []TriggerInterceptor
`serviceAccountName` string	(Optional) ServiceAccountName optionally associates credentials with each trigger; Unlike EventListeners, this should be scoped to the same namespace as the Trigger itself

TriggerSpecBinding

(Appears on:TriggerSpec)

Field	Description
`name` string	Name is the name of the binding param Mutually exclusive with Ref
`value` string	Value is the value of the binding param. Can contain JSONPath Has to be pointer since “” is a valid value Required if Name is also specified.
`ref` string	Ref is a reference to a TriggerBinding kind. Mutually exclusive with Name
`kind` TriggerBindingKind	Kind can only be provided if Ref is also provided. Defaults to TriggerBinding
`apiversion` string	APIVersion of the binding ref

TriggerSpecTemplate

(Appears on:TriggerSpec)

Field Description

ref
string

apiversion
string

spec
TriggerTemplateSpec

TriggerTemplateSpec

(Appears on:TriggerTemplate, TriggerSpecTemplate)

TriggerTemplateSpec holds the desired state of TriggerTemplate

Field	Description
`params` []ParamSpec
`resourcetemplates` []TriggerResourceTemplate

TriggerTemplateStatus

(Appears on:TriggerTemplate)

TriggerTemplateStatus describes the desired state of TriggerTemplate

WebhookInterceptor

(Appears on:TriggerInterceptor)

WebhookInterceptor provides a webhook to intercept and pre-process events

Field	Description
`objectRef` Kubernetes core/v1.ObjectReference	(Optional) ObjectRef is a reference to an object that will resolve to a cluster DNS name to use as the EventInterceptor. Either objectRef or url can be specified
`url` knative.dev/pkg/apis.URL	(Optional)
`header` []github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param	Header is a group of key-value pairs that can be appended to the interceptor request headers. This allows the interceptor to make decisions specific to an EventListenerTrigger.

Generated with gen-crd-api-reference-docs .

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Triggers Controller Metrics

The following tekton triggers metrics are available at controller-service on port 9000.

We expose several kinds of exporters, including Prometheus, Google Stackdriver, and many others. You can set them up using observability configuration.

Name	Type	Description
`controller_clusterinterceptor_count`	Gauge	Number of clusterinteceptor
`controller_eventlistener_count`	Gauge	Number of eventlistener
`controller_clustertriggerbinding_count`	Gauge	Number of clustertriggerbinding
`controller_triggerbinding_count`	Gauge	Number of triggerbinding
`controller_triggertemplate_count`	Gauge	Number of triggertemplate

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting Tekton Triggers

This page describes the debugging methods you can use to diagnose and fix issues with Tekton Triggers.

Gathering `EventListener` logs

You can gather EventListener logs using the Tekton tkn CLI tool or the Kubernetes kubectl CLI tool.

Use the following tkn command to gather EventListener logs:

$ tkn eventlistener logs <eventlistener-name>

See the tkn CLI tool documentation page for this config for more information.

Use the following kubectl command to gather EventListener logs:

$ kubectl logs deploy/el-<insert name of eventlistener> -n <namespace>

To get a list of EventListeners for a given namespace, use the following command:

$ kubectl get el -n <namespace>
NAME                  ADDRESS                                                        AVAILABLE   REASON
test-event-listener   http://el-test-event-listener.default.svc.cluster.local:8080   True        MinimumReplicasAvailable

Configuring debug logging for `EventListeners`

EventListeners uses ConfigMap named config-logging-triggers in the namespace(typically tekton-pipelines) of the target Tekton Triggers controller. To view this ConfigMap, use the following command:

$ kubectl get cm -n tekton-pipelines
NAME                      DATA   AGE
config-logging-triggers   2      28m

Below is a typical config-logging-listeners ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-logging-triggers
data:
  loglevel.eventlistener: info
  zap-logger-config: '{"level": "info","development": false,"sampling": {"initial":
    100,"thereafter": 100},"outputPaths": ["stdout"],"errorOutputPaths": ["stderr"],"encoding":
    "json","encoderConfig": {"timeKey": "ts","levelKey": "level","nameKey": "logger","callerKey":
    "caller","messageKey": "msg","stacktraceKey": "stacktrace","lineEnding": "","levelEncoder":
    "","timeEncoder": "iso8601","durationEncoder": "","callerEncoder": ""}}'

To enable debug-level logging in Tekton Triggers, use the following command:

$ kubectl patch cm config-logging-triggers -n tekton-pipelines  -p '{"data": {"zap-logger-config": "{\n  \"level\": \"debug\",\n  \"development\": false,\n  \"sampling\": {\n    \"initial\": 100,\n    \"thereafter\": 100\n  },\n  \"outputPaths\": [\"stdout\"],\n  \"errorOutputPaths\": [\"stderr\"],\n  \"encoding\": \"json\",\n  \"encoderConfig\": {\n    \"timeKey\": \"ts\",\n    \"levelKey\": \"level\",\n    \"nameKey\": \"logger\",\n    \"callerKey\": \"caller\",\n    \"messageKey\": \"msg\",\n    \"stacktraceKey\": \"stacktrace\",\n    \"lineEnding\": \"\",\n    \"levelEncoder\": \"\",\n    \"timeEncoder\": \"iso8601\",\n    \"durationEncoder\": \"\",\n    \"callerEncoder\": \"\"\n  }\n}\n"}}'

You need to delete deployment of EventListener so that above configuration are applied to Environment variables of Deployment.

$ kubectl delete deployment/el-{EventListenerName}

The EventListener will start with the new logging level. For example:

{"level":"info","ts":"2022-07-26T16:02:26.191Z","caller":"logging/config.go:116","msg":"Successfully created the logger."}
{"level":"info","ts":"2022-07-26T16:02:26.191Z","caller":"logging/config.go:117","msg":"Logging level set to: debug"}

From this point on, every HTTP request that the EventListener logs contains additional information. For example:

{"level":"debug","ts":"2021-02-10T08:42:30.915Z","logger":"eventlistener","caller":"sink/sink.go:93","msg":"EventListener: demo-event-listener in Namespace: default handling event (EventID: 9x4mb) with path /testing, payload: {\"testing\": \"value\"} and header: map[Accept:[*/*] Content-Length:[20] Content-Type:[application/x-www-form-urlencoded] User-Agent:[curl/7.61.1] X-Auth:[testing]]","knative.dev/controller":"eventlistener","/triggers-eventid":"9x4mb","logging.googleapis.com/labels":{},"logging.googleapis.com/sourceLocation":{"file":"github.com/tektoncd/triggers/pkg/sink/sink.go","line":"93","function":"github.com/tektoncd/triggers/pkg/sink.Sink.HandleEvent"}}

WARNING: The EventListener logs all payload headers verbatim. This includes any sensitive information the headers might contain.

To disable debug-level logging, use the following command:

$ kubectl patch cm config-logging-triggers -n <namespace> -p '{"data": {"loglevel.eventlistener": "info"}}'

This returns the logging level to info.

Troubleshooting JSONPath issues

You may see the following message in your logs:

{"level":"error","ts":"2021-02-10T08:43:47.409Z","logger":"eventlistener","caller":"sink/sink.go:230","msg":"failed to ApplyEventValuesToParams: failed to replace JSONPath value for param message: $(body.message): message is not found","knative.dev/controller":"eventlistener","/triggers-eventid":"c8f88","/trigger":"demo-trigger","logging.googleapis.com/labels":{},"logging.googleapis.com/sourceLocation":{"file":"github.com/tektoncd/triggers/pkg/sink/sink.go","line":"230","function":"github.com/tektoncd/triggers/pkg/sink.Sink.processTrigger"},"stacktrace":"github.com/tektoncd/triggers/pkg/sink.Sink.processTrigger\n\tgithub.com/tektoncd/triggers/pkg/sink/sink.go:230\ngithub.com/tektoncd/triggers/pkg/sink.Sink.HandleEvent.func1\n\tgithub.com/tektoncd/triggers/pkg/sink/sink.go:125"}

This means that the selected Interceptor is unable to parse the structure of the received JSON payload. To troubleshoot this, you must capture and inspect the payload for inconsistencies.

Troubleshooting signature and token errors

When sending a hook protected by a secret, GitHub includes an X-Hub-Signature object in the header, while GitLab includes an X-GitLab-Token object. You may see no X-Hub-Signature set and/or no X-GitLab-Token header set errors in your logs in one of the following scenarios:

If you specify a secret in your Interceptor but don’t specify it in the hook.
You are sending unsigned payloads to an Interceptor that expects signed payloads.

Note that depending on how you have configured your Tekton Triggers stack, these errors may not indicate an actual problem. For example, your stack may include some Interceptors that expect signed payloads and some that expected unsigned payloads. Since Tekton Triggers processes all Interceptors concurrently, Interceptors that expect signed payloads will log the above errors, while Interceptors that expect unsigned payloads will process those payloads successfully.

Tekton – Triggers and EventListeners

Vault: Install and set up Tekton Triggers

Prerequisites

Installation

Customization options

Further reading

Vault:

EventListeners

Structure of an EventListener

Specifying the Kubernetes service account

Specifying Triggers

Specifying cloudEventURI

Specifying TriggerGroups

Specifying Resources

Specifying a kubernetesResource object

Specifying Service configuration

Specifying Replicas

Specifying a CustomResource object

Contract for the CustomResource object

Specifying Interceptors

Constraining EventListeners to specific namespaces

Constraining EventListeners to specific labels

Specifying EventListener timeouts

Disabling Payload Validation

Labels in EventListeners

Annotations in EventListeners

Understanding EventListener response

Response to CloudEvents

Deprecated Fields

TLS HTTPS support in EventListeners

Obtaining the status of deployed EventListeners

Configuring logging for EventListeners

Configuring metrics for EventListeners

Exposing an EventListener outside of the cluster

Exposing an EventListener using a LoadBalancer Service

Exposing an EventListener using a Kubernetes Ingress object

Exposing an EventListener using Openshift Route

Understanding the deployment of an EventListener

Deploying EventListeners in multi-tenant scenarios

Deploying each EventListener in its own namespace

Deploying multiple EventListeners in the same namespace

Cloud Events during Trigger Processing

Vault:

TriggerTemplates

Structure of a TriggerTemplate

Specifying parameters

Embedding JSON objects within resource templates

Vault:

TriggerBindings

Structure of a TriggerBinding

Inline bindings

TriggerBindings

ClusterTriggerBindings

Specifying parameters

Accessing data in HTTP JSON payloads

Accessing data added by Interceptors

Accessing EventListener Event Context

Accessing JSON keys containing special characters like (.) or (/)

Fallback to default values

Field binding examples

Specifying multiple bindings

Troubleshooting TriggerBindings

Vault:

ClusterInterceptors

Structure of a ClusterInterceptor

Configuring the client of the ClusterInterceptor

Configuring a Kubernetes Service for the ClusterInterceptor

Running ClusterInterceptor as HTTPS

Vault:

Configuring Interceptors

Overview

Specifying an Interceptor

Webhook Interceptors

GitHub Interceptors

Adding Changed Files

Adding Changed Files - Private Repository

Owners validation for pull requests

GitLab Interceptors

Bitbucket Interceptors

Bitbucket Server

`EventListeners`

Structure of an `EventListener`

Specifying `Triggers`

Specifying `cloudEventURI`

Specifying `TriggerGroups`

Specifying `Resources`

Specifying a `kubernetesResource` object

Specifying `Service` configuration

Specifying `Replicas`

Specifying a `CustomResource` object

Contract for the `CustomResource` object

Specifying `Interceptors`

Constraining `EventListeners` to specific namespaces

Constraining `EventListeners` to specific labels

Specifying `EventListener` timeouts

Labels in `EventListeners`

Annotations in `EventListeners`

Understanding `EventListener` response

TLS HTTPS support in `EventListeners`

Obtaining the status of deployed `EventListeners`

Configuring logging for `EventListeners`

Configuring metrics for `EventListeners`

Exposing an `EventListener` outside of the cluster

Exposing an `EventListener` using a `LoadBalancer` Service

Exposing an `EventListener` using a Kubernetes `Ingress` object

Exposing an `EventListener` using Openshift Route

Understanding the deployment of an `EventListener`

Deploying `EventListeners` in multi-tenant scenarios

Deploying each `EventListener` in its own namespace

Deploying multiple `EventListeners` in the same namespace

`TriggerTemplates`

Structure of a `TriggerTemplate`

`TriggerBindings`

Structure of a `TriggerBinding`

`TriggerBindings`

`ClusterTriggerBindings`

Accessing data added by `Interceptors`

Accessing JSON keys containing special characters like (`.`) or (`/`)

Troubleshooting `TriggerBindings`

`ClusterInterceptors`

Structure of a `ClusterInterceptor`

Configuring the client of the `ClusterInterceptor`

Configuring a Kubernetes Service for the `ClusterInterceptor`

Configuring `Interceptors`

Specifying an `Interceptor`

Webhook `Interceptors`

Bitbucket `Interceptors`

Chaining `Interceptors`

Implementing custom `Interceptors`

`Interceptors`

Structure of a `Interceptor`

Configuring the client of the `Interceptor`

Configuring a Kubernetes Service for the `Interceptor`

`Triggers`

Structure of a `Trigger`

Specifying the corresponding `TriggerTemplate`

Events in `EventListener`

InterceptorKind (`string` alias)