Skip to content

Commit 677627f

Browse files
mattmoortekton-robot
mattmoor
authored and
tekton-robot
committed
Format markdown
Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)` /assign ImJasonH dibyom /cc ImJasonH dibyom
1 parent bc6916b commit 677627f

17 files changed

+378
-260
lines changed

‎CONTRIBUTING.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ For more Triggers specific guidelines, see:
3232

3333
- [The Tekton Triggers ZenHub project](#zenhub-project)
3434

35-
See also [the Tekton Pipelines roadmap](http://github.com/tektoncd/pipeline/blob/master/roadmap-2019.md)
35+
See also
36+
[the Tekton Pipelines roadmap](http://github.com/tektoncd/pipeline/blob/master/roadmap-2019.md)
3637

3738
## ZenHub project
3839

‎DEVELOPMENT.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ of the technology this project is built on.
2424

2525
#### Ramp up on CRDs
2626

27-
This project extends Kubernetes (aka
28-
`k8s`) with Custom Resource Definitions (CRDSs). To find out more:
27+
This project extends Kubernetes (aka `k8s`) with Custom Resource Definitions
28+
(CRDSs). To find out more:
2929

3030
- [The Kubernetes docs on Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -
3131
These will orient you on what words like "Resource" and "Controller"
@@ -193,8 +193,8 @@ kubectl create clusterrolebinding cluster-admin-binding \
193193
To install [Tekton Pipelines](https://github.com/tektoncd/pipeline) you can
194194
either:
195195

196-
* [Install a released version](https://github.com/tektoncd/pipeline/blob/master/docs/install.md)
197-
* [Setup Tekton Pipelines for development](https://github.com/tektoncd/pipeline/blob/master/DEVELOPMENT.md)
196+
- [Install a released version](https://github.com/tektoncd/pipeline/blob/master/docs/install.md)
197+
- [Setup Tekton Pipelines for development](https://github.com/tektoncd/pipeline/blob/master/DEVELOPMENT.md)
198198
(install and iterate from HEAD)
199199

200200
## Iterating

‎README.md

+58-19
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,76 @@
11
# Tekton Triggers
2-
Triggers is a Kubernetes [Custom Resource Defintion](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRD) controller that allows you to extract information from events payloads (a "trigger") to create Kubernetes resources.
32

4-
The contents of this repo originated from implementing [this design](https://docs.google.com/document/d/1fngeNn3kGD4P_FTZjAnfERcEajS7zQhSEUaN7BYIlTw/edit#heading=h.iyqzt1brkg3o)
5-
(visible to members of [the Tekton mailing list](https://github.com/tektoncd/community/blob/master/contact.md#mailing-list)).
3+
Triggers is a Kubernetes
4+
[Custom Resource Defintion](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
5+
(CRD) controller that allows you to extract information from events payloads (a
6+
"trigger") to create Kubernetes resources.
7+
8+
The contents of this repo originated from implementing
9+
[this design](https://docs.google.com/document/d/1fngeNn3kGD4P_FTZjAnfERcEajS7zQhSEUaN7BYIlTw/edit#heading=h.iyqzt1brkg3o)
10+
(visible to members of
11+
[the Tekton mailing list](https://github.com/tektoncd/community/blob/master/contact.md#mailing-list)).
612

713
## Background
8-
[Tekton](https://github.com/tektoncd/pipeline) is a **Kubernetes-native**, continuous integration and delivery (CI/CD) framework that enables you to create containerized, composable, and configurable workloads declaratively through CRDs.
9-
Naturally, CI/CD events contain information that should:
10-
- Identify the kind of event (GitHub Push, Gitlab Issue, Docker Hub Webhook, etc.)
11-
- Be accessible from and map to particular pipelines (Take SHA from payload to use it in pipeline X)
12-
- Deterministically trigger pipelines (Events/pipelines that trigger pipelines based on certain payload values)
1314

14-
The Tekton API enables functionality to be seperated from configuration (e.g. [Pipelines](https://github.com/tektoncd/pipeline/blob/master/docs/pipelines.md) vs [PipelineRuns](https://github.com/tektoncd/pipeline/blob/master/docs/pipelineruns.md)) such that steps can be reusable, but it does not provide a mechanism to generate the resources (notably, [PipelineRuns](https://github.com/tektoncd/pipeline/blob/master/docs/pipelineruns.md) and [PipelineResources](https://github.com/tektoncd/pipeline/blob/master/docs/resources.md#pipelineresources)) that encapsulate these configurations dynamically. Triggers extends the Tekton architecture with the following CRDs:
15-
- [`TriggerTemplate`](docs/triggertemplates.md) - Templates resources to be created (e.g. Create PipelineResources and PipelineRun that uses them)
16-
- [`TriggerBinding`](docs/triggerbindings.md) - Validates events and extracts payload fields
17-
- [`EventListener`](docs/eventlisteners.md) - Connects `TriggerBindings` and `TriggerTemplates` into an [addressable](https://github.com/knative/eventing/blob/master/docs/spec/interfaces.md) endpoint (the event sink). It uses the extracted event parameters from each `TriggerBinding` (and any supplied static parameters) to create the resources specified in the corresponding `TriggerTemplate`. It also optionally allows an external service to pre-process the event payload via the `interceptor` field.
15+
[Tekton](https://github.com/tektoncd/pipeline) is a **Kubernetes-native**,
16+
continuous integration and delivery (CI/CD) framework that enables you to create
17+
containerized, composable, and configurable workloads declaratively through
18+
CRDs. Naturally, CI/CD events contain information that should:
19+
20+
- Identify the kind of event (GitHub Push, Gitlab Issue, Docker Hub Webhook,
21+
etc.)
22+
- Be accessible from and map to particular pipelines (Take SHA from payload to
23+
use it in pipeline X)
24+
- Deterministically trigger pipelines (Events/pipelines that trigger pipelines
25+
based on certain payload values)
26+
27+
The Tekton API enables functionality to be seperated from configuration (e.g.
28+
[Pipelines](https://github.com/tektoncd/pipeline/blob/master/docs/pipelines.md)
29+
vs
30+
[PipelineRuns](https://github.com/tektoncd/pipeline/blob/master/docs/pipelineruns.md))
31+
such that steps can be reusable, but it does not provide a mechanism to generate
32+
the resources (notably,
33+
[PipelineRuns](https://github.com/tektoncd/pipeline/blob/master/docs/pipelineruns.md)
34+
and
35+
[PipelineResources](https://github.com/tektoncd/pipeline/blob/master/docs/resources.md#pipelineresources))
36+
that encapsulate these configurations dynamically. Triggers extends the Tekton
37+
architecture with the following CRDs:
1838

39+
- [`TriggerTemplate`](docs/triggertemplates.md) - Templates resources to be
40+
created (e.g. Create PipelineResources and PipelineRun that uses them)
41+
- [`TriggerBinding`](docs/triggerbindings.md) - Validates events and extracts
42+
payload fields
43+
- [`EventListener`](docs/eventlisteners.md) - Connects `TriggerBindings` and
44+
`TriggerTemplates` into an
45+
[addressable](https://github.com/knative/eventing/blob/master/docs/spec/interfaces.md)
46+
endpoint (the event sink). It uses the extracted event parameters from each
47+
`TriggerBinding` (and any supplied static parameters) to create the resources
48+
specified in the corresponding `TriggerTemplate`. It also optionally allows an
49+
external service to pre-process the event payload via the `interceptor` field.
1950

20-
Using `tektoncd/triggers` in conjunction with `tektoncd/pipeline` enables you to easily create full-fledged CI/CD systems where the execution is defined **entirely** through Kubernetes resources.
21-
This repo draws inspiration from `Tekton`, but can used stand alone since `TriggerTemplates` can create any Kubernetes resource.
51+
Using `tektoncd/triggers` in conjunction with `tektoncd/pipeline` enables you to
52+
easily create full-fledged CI/CD systems where the execution is defined
53+
**entirely** through Kubernetes resources. This repo draws inspiration from
54+
`Tekton`, but can used stand alone since `TriggerTemplates` can create any
55+
Kubernetes resource.
2256

2357
You can learn more by checking out the [docs](docs/README.md)
2458

2559
## Want to start using Tekton Triggers
2660

27-
[Install](./docs/install.md) Triggers, check out the [installation guide](./docs/install.md), [examples](./examples/README.md) or follow the [getting started guide](./docs/getting-started/README.md) to become familiar with the project. The getting started guide walks through setting up an end-to-end image building solution, which will be triggered from GitHub `push` events.
61+
[Install](./docs/install.md) Triggers, check out the
62+
[installation guide](./docs/install.md), [examples](./examples/README.md) or
63+
follow the [getting started guide](./docs/getting-started/README.md) to become
64+
familiar with the project. The getting started guide walks through setting up an
65+
end-to-end image building solution, which will be triggered from GitHub `push`
66+
events.
2867

2968
### Read the docs
3069

31-
| Version | Docs | Examples | Getting Started |
32-
| ------- | ---- | -------- | --------------- |
33-
| [HEAD](https://github.com/tektoncd/triggers/blob/master/DEVELOPMENT.md#install-pipeline) | [Docs @ HEAD](https://github.com/tektoncd/triggers/blob/master/docs/README.md) | [Examples @ HEAD](https://github.com/tektoncd/triggers/blob/master/examples) | [Getting Started @ HEAD](https://github.com/tektoncd/triggers/blob/master/docs/getting-started#getting-started-with-triggers) |
34-
| [v0.1.0](https://github.com/tektoncd/triggers/releases/tag/v0.1.0) | [Docs @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/docs#tekton-triggers) | [Examples @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/examples#examples) | [Getting Started @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/docs/getting-started#getting-started-with-triggers) |
70+
| Version | Docs | Examples | Getting Started |
71+
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
72+
| [HEAD](https://github.com/tektoncd/triggers/blob/master/DEVELOPMENT.md#install-pipeline) | [Docs @ HEAD](https://github.com/tektoncd/triggers/blob/master/docs/README.md) | [Examples @ HEAD](https://github.com/tektoncd/triggers/blob/master/examples) | [Getting Started @ HEAD](https://github.com/tektoncd/triggers/blob/master/docs/getting-started#getting-started-with-triggers) |
73+
| [v0.1.0](https://github.com/tektoncd/triggers/releases/tag/v0.1.0) | [Docs @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/docs#tekton-triggers) | [Examples @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/examples#examples) | [Getting Started @ v0.1.0](https://github.com/tektoncd/triggers/tree/v0.1.0/docs/getting-started#getting-started-with-triggers) |
3574

3675
## Want to contribute
3776

‎code-of-conduct.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,4 +72,4 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
7272
version 1.4, available at
7373
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
7474

75-
[homepage]: https://www.contributor-covenant.org
75+
[homepage]: https://www.contributor-covenant.org

‎docs/README.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
# Tekton Triggers
2-
Triggers enables users to map fields from an event payload into resource templates. Put another way, this allows events to both model and instantiate themselves as Kubernetes resources. In the case of `tektoncd/pipeline`, this makes it easy to encapsulate configuration into `PipelineRun`s and `PipelineResource`s.
2+
3+
Triggers enables users to map fields from an event payload into resource
4+
templates. Put another way, this allows events to both model and instantiate
5+
themselves as Kubernetes resources. In the case of `tektoncd/pipeline`, this
6+
makes it easy to encapsulate configuration into `PipelineRun`s and
7+
`PipelineResource`s.
38

49
![TriggerFlow](../images/TriggerFlow.png)
510

611
## Learn More
12+
713
See the following links for more on each of the resources involved:
14+
815
- [`TriggerTemplate`](triggertemplates.md)
916
- [`TriggerBinding`](triggerbindings.md)
1017
- [`EventListener`](eventlisteners.md)
1118

1219
## Getting Started Tasks
20+
1321
- [Create an Ingress on the EventListener Service](create-ingress.yaml)
1422
- [Create a GitHub webhook](create-webhook.yaml)

‎docs/cel_expressions.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ headers are also available.
4545
</tr>
4646
</table>
4747

48-
NOTE: The header value is a Go `http.Header`, which is [defined](https://golang.org/pkg/net/http/#Header) as:
48+
NOTE: The header value is a Go `http.Header`, which is
49+
[defined](https://golang.org/pkg/net/http/#Header) as:
4950

5051
```go
5152
type Header map[string][]string
@@ -54,11 +55,10 @@ type Header map[string][]string
5455
i.e. the header is a mapping of strings, to arrays of strings, see the `match`
5556
function on headers below for an extension that makes looking up headers easier.
5657

57-
5858
### List of extension functions
5959

60-
This lists custom functions that can be used from CEL expressions in the
61-
CEL interceptor.
60+
This lists custom functions that can be used from CEL expressions in the CEL
61+
interceptor.
6262

6363
<table style="width=100%" border="1">
6464
<tr>

‎docs/eventlisteners.md

+20-19
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ resources will be created (or at least attempted) with. The service account must
77
have the following role bound.
88

99
<!-- FILE: examples/role-resources/role.yaml -->
10+
1011
```YAML
1112
kind: Role
1213
apiVersion: rbac.authorization.k8s.io/v1
@@ -26,7 +27,6 @@ rules:
2627
verbs: ["create"]
2728
```
2829
29-
3030
Note that currently, JSON is the only accepted MIME type for events.
3131
3232
When an `EventListener` is successfully created, a service is created that
@@ -53,11 +53,11 @@ make it reachable externally.
5353
By default, EventListeners will attach the following labels automatically to all
5454
resources created:
5555

56-
Name | Description
57-
------------------------ | -----------
58-
tekton.dev/eventlistener | Name of the EventListener that generated the resource.
59-
tekton.dev/trigger | Name of the trigger that generated the resource.
60-
tekton.dev/eventid | UID of the incoming event.
56+
| Name | Description |
57+
| ------------------------ | ------------------------------------------------------ |
58+
| tekton.dev/eventlistener | Name of the EventListener that generated the resource. |
59+
| tekton.dev/trigger | Name of the trigger that generated the resource. |
60+
| tekton.dev/eventid | UID of the incoming event. |
6161

6262
## Event Interceptors
6363

@@ -66,9 +66,9 @@ modify the behavior or payload of triggers.
6666

6767
Event Interceptors can take several different forms today:
6868

69-
* Webhook Interceptors
70-
* GitHub Interceptors
71-
* GitLab Interceptors
69+
- Webhook Interceptors
70+
- GitHub Interceptors
71+
- GitLab Interceptors
7272

7373
### Webhook Interceptors
7474

@@ -100,14 +100,16 @@ binding/templating.
100100

101101
To be an Event Interceptor, a Kubernetes object should:
102102

103-
* Be fronted by a regular Kubernetes v1 Service over port 80
104-
* Accept JSON payloads over HTTP
105-
* Return a HTTP 200 OK Status if the EventListener should continue processing the event
106-
* Return a JSON body back. This will be used by the EventListener as the event payload
107-
for any further processing. If the interceptor does not need to modify the body, it can
108-
simply return the body that it received.
103+
- Be fronted by a regular Kubernetes v1 Service over port 80
104+
- Accept JSON payloads over HTTP
105+
- Return a HTTP 200 OK Status if the EventListener should continue processing
106+
the event
107+
- Return a JSON body back. This will be used by the EventListener as the event
108+
payload for any further processing. If the interceptor does not need to modify
109+
the body, it can simply return the body that it received.
109110

110111
<!-- FILE: examples/eventlisteners/eventlistener-interceptor.yaml -->
112+
111113
```YAML
112114
---
113115
apiVersion: tekton.dev/v1alpha1
@@ -138,7 +140,6 @@ spec:
138140
name: pipeline-template
139141
```
140142

141-
142143
### GitHub Interceptors
143144

144145
GitHub interceptors contain logic to validate and filter webhooks that come from
@@ -160,6 +161,7 @@ The body/header of the incoming request will be preserved in this interceptor's
160161
response.
161162

162163
<!-- FILE: examples/eventlisteners/github-eventlistener-interceptor.yaml -->
164+
163165
```YAML
164166
---
165167
apiVersion: tekton.dev/v1alpha1
@@ -184,7 +186,6 @@ spec:
184186
name: pipeline-template
185187
```
186188

187-
188189
### GitLab Interceptors
189190

190191
GitLab interceptors contain logic to validate and filter requests that come from
@@ -207,6 +208,7 @@ The body/header of the incoming request will be preserved in this interceptor's
207208
response.
208209

209210
<!-- FILE: examples/eventlisteners/gitlab-eventlistener-interceptor.yaml -->
211+
210212
```YAML
211213
---
212214
apiVersion: tekton.dev/v1alpha1
@@ -231,7 +233,6 @@ spec:
231233
name: pipeline-template
232234
```
233235

234-
235236
### CEL Interceptors
236237

237238
CEL interceptors parse expressions to filter requests based on JSON bodies and
@@ -244,6 +245,7 @@ The body/header of the incoming request will be preserved in this interceptor's
244245
response.
245246

246247
<!-- FILE: examples/eventlisteners/cel-eventlistener-interceptor.yaml -->
248+
247249
```YAML
248250
apiVersion: tekton.dev/v1alpha1
249251
kind: EventListener
@@ -262,6 +264,5 @@ spec:
262264
name: pipeline-template
263265
```
264266

265-
266267
The `expression` must return a `true` value, otherwise the request will be
267268
filtered out.

0 commit comments

Comments
 (0)