triggerbindings.md

TriggerBindings

As per the name, TriggerBindings bind against events/triggers. TriggerBindings enable you to capture fields from an event and store them as parameters. The separation of TriggerBindings from TriggerTemplates was deliberate to encourage reuse between them.

apiVersion: triggers.tekton.dev/v1alpha1
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)

TriggerBindings are connected to TriggerTemplates within an EventListener, which is where the pod is actually instantiated that "listens" for the respective events.

Parameters

TriggerBindings can provide params which are passed to a TriggerTemplate. Each parameter has a name and a value.

Event Variable Interpolation

TriggerBindings can access values from the HTTP JSON body and the headers using JSONPath expressions wrapped in $(). The key in the header is case-insensitive.

These are all valid expressions:

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

These are invalid expressions:

.body.key1 # INVALID - Not wrapped in $()
$({body) # INVALID - Ending curly brace absent

If the $() is embedded inside another $() we will use the contents of the innermost $() as the JSONPath expression

$($(body.b)) -> $(body.b)
$($($(body.b))) -> $(body.b)

Keys with dots .

To access JSON keys that contain . character, we need to escape the . e.g.

# body contains a filed called "tekton.dev" e.g. {"body": {"tekton.dev": "triggers"}}
$(body.tekton\.dev) -> "triggers"

Defaulting

If the HTTP headers and body contents from an event fail to resolve the JSONPath expressions supplied, and attempt will be made to utilize the default value, if supplied, from the associated TriggerTemplate.

Examples

`$(body)` is 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) is replaced by all of the 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"

Multiple Bindings

In an EventListener, you may specify multiple bindings as part of your trigger. This allows you to create reusable bindings that can be mixed and matched with various triggers. For example, a trigger with one binding that extracts event information, and another binding that provides deploy environment information:

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

Debugging

Evaluating TriggerBindings

As a convenience, the binding-eval tool allows you to evaluate TriggerBindings for a given HTTP request to determine what the resulting parameters would be during trigger execution.

$ 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"
  }
]

To install, run:

$ go get -u github.com/tektoncd/triggers/cmd/binding-eval