Tekton Triggers

A CRD for a long-running HTTP sink that receives events and evaluates every Trigger it serves against each one.

It is the only part that is always running. It replies 202 Accepted right away and processes the event asynchronously, so a 202 from the listener does not mean a PipelineRun was created.

For each EventListener the controller creates a Deployment and a Service named el-<name>, listening on port 8080.

The Service is ClusterIP by default, so you must expose it yourself (Ingress, OpenShift Route or a LoadBalancer serviceType) before GitHub can reach it. Replicas scale the sink horizontally, and cloudEventURI makes it emit CloudEvents about each event it handles.

Groups interceptors, bindings and a template into one unit. It can be written inline in an EventListener or as its own CRD.

As standalone CRDs, Triggers can live in team namespaces and be picked up by a shared listener through selectors. Each one can set its own serviceAccountName for the objects it creates.

A namespaced list of params whose values are expressions over the event, like $(body.head_commit.id).

It separates reading the payload from the PipelineRun shape, so the same template can serve GitHub, GitLab or a cron job as long as each one has its own binding.

A cluster-scoped TriggerBinding that any Trigger in any namespace can reference with kind: ClusterTriggerBinding.

Mappings for a provider's payload are the same everywhere, so you define them once. A ref without kind looks for a namespaced TriggerBinding in the Trigger's own namespace, which is a common cause of 'not found'.

Declares params (optionally with defaults) and resourcetemplates, the Kubernetes objects to create for each event.

It is the blueprint for a run. The listener substitutes $(tt.params.x) into it and creates the result with its own ServiceAccount, so that account needs RBAC to create PipelineRuns.

The placeholder syntax inside resourcetemplates that is replaced with the bound or default value of a template param.

A param that is neither bound nor defaulted is not an error: the literal placeholder ends up in the created object, which then fails later in a confusing way.

The list of objects in a TriggerTemplate. Usually one PipelineRun, but any Tekton or Kubernetes resource the ServiceAccount may create.

One event creates every object in the list, every time. Triggers keeps no memory of earlier events, so deduplication has to come from naming or from the pipeline itself.

metadata.generateName asks the API server to add a random 5-character suffix, so every created PipelineRun gets a unique name.

A fixed name works once and then fails with AlreadyExists. A name derived from the commit SHA dedupes redeliveries but blocks reruns. generateName never collides, but builds a redelivered commit twice.

A step in a Trigger's chain that can validate, filter or enrich the event before bindings run. Any interceptor can stop the chain.

Interceptors run in order and each sees the extensions added by earlier ones. The chain stops at the first continue: false, so cheap checks like signature validation should come first.

A cluster-scoped CRD that registers an interceptor as an HTTPS service. The listener POSTs it an InterceptorRequest and reads back an InterceptorResponse.

The built-in github, gitlab, bitbucket, cel and slack interceptors are ClusterInterceptors served by tekton-triggers-core-interceptors. You can register your own the same way via spec.clientConfig.service.

Validates X-Hub-Signature-256 against a secret and filters on X-GitHub-Event with an eventTypes list.

Without it, anyone who finds your webhook URL can start pipelines with any payload they like. eventTypes keeps push-only Triggers from firing on ping or issue events.

Provider-specific equivalents of the GitHub interceptor. GitLab compares the X-Gitlab-Token shared token; Bitbucket Server checks an HMAC in X-Hub-Signature.

Each provider authenticates and names events differently (Push Hook, repo:refs_changed). The interceptor hides that so the rest of the chain looks the same.

Evaluates a Common Expression Language filter over body and header. The event continues only if it returns true.

Branch, path and action filtering without writing a service. Triggers adds functions such as match, truncate, split, compareSecret and parseJSON to standard CEL.

Key/expression pairs on the CEL interceptor whose results are added to the event's extensions.

Bindings can only copy fields. Overlays compute new ones (a 7-char SHA, a branch name without refs/heads/) so the template stays simple.

The older style of custom interceptor: a plain Kubernetes Service that receives the raw HTTP event and returns 200 to continue.

Its response body and headers replace the event's, so it can rewrite payloads. It doesn't use the InterceptorRequest protocol, and new interceptors should usually be ClusterInterceptors instead.

A shared secret configured both in the Git provider's webhook settings and in a Kubernetes Secret that the interceptor reads via secretRef.

The two copies have to match. After a rotation that misses one side, every event is dropped silently while the provider still sees a 202.

sha256=HMAC-SHA256(secret, raw body), sent in X-Hub-Signature-256 and recomputed by the interceptor.

It proves the sender knows the secret and that the body wasn't changed in transit. One changed byte gives a completely different digest, and the comparison is constant-time so timing doesn't leak the expected value.

The three roots a binding value can read: the JSON body (JSONPath-like, with [i] indexes), HTTP headers (case-insensitive), and interceptor extensions.

Values can be mixed with literals ("pr-$(body.number)"), and $(body) on its own gives the whole payload as a JSON string. A path that doesn't exist fails the binding for that event.

Selectors that let one EventListener serve Trigger CRDs from other namespaces (matchNames, "*") and/or only those with matching labels.

This is how platform teams run one listener for many teams. The listener's ServiceAccount must be allowed to read Triggers, bindings and templates in those namespaces, or they are silently skipped and the errors show up only in its logs.