Stitch any CI into Tangled
1# Tekton
2
3The Tekton provider runs only in Kubernetes. Tack receives Tangled
4pipeline triggers, creates a Tekton `PipelineRun` for an existing
5in-cluster `Pipeline`, watches that `PipelineRun`, and publishes
6`sh.tangled.pipeline.status` records back to Tangled.
7
8Tekton Triggers are intentionally not used. Tack already performs the
9event-to-run translation, and Tekton's native execution object is the
10`PipelineRun`.
11
12## Required cluster setup
13
14* Tekton Pipelines is installed in the cluster.
15* Tack is deployed inside the same cluster.
16* The target Tekton `Pipeline` objects already exist in the namespace
17 tack is configured to use.
18* Tack's Kubernetes service account has RBAC to:
19 * create, get, list, and watch `tekton.dev` `pipelineruns`
20 * get, list, and watch `tekton.dev` `taskruns`
21 * get and list pods
22 * get pod logs via `pods/log`
23
24Example RBAC:
25
26```yaml
27apiVersion: rbac.authorization.k8s.io/v1
28kind: Role
29metadata:
30 name: tack-tekton
31 namespace: ci
32rules:
33 - apiGroups: ["tekton.dev"]
34 resources: ["pipelineruns"]
35 verbs: ["create", "get", "list", "watch"]
36 - apiGroups: ["tekton.dev"]
37 resources: ["taskruns"]
38 verbs: ["get", "list", "watch"]
39 - apiGroups: [""]
40 resources: ["pods"]
41 verbs: ["get", "list"]
42 - apiGroups: [""]
43 resources: ["pods/log"]
44 verbs: ["get"]
45```
46
47## Configure Tack
48
49| Env var | Description |
50| ------------------------ | --------------------------------------------------------- |
51| `TACK_TEKTON_ENABLED` | Set to `1` to enable the Tekton provider |
52| `TACK_TEKTON_NAMESPACE` | Namespace for created `PipelineRun`s (default `default`) |
53
54The provider uses Kubernetes in-cluster service account credentials.
55It will not run from a local kubeconfig.
56
57## Naming
58
59There are three separate names:
60
61* Tack workflow name: the Tangled workflow filename/name, e.g. `ci.yml`.
62 This remains the Tangled-facing workflow identity in status records.
63* Tekton `Pipeline` name: the existing in-cluster pipeline definition,
64 e.g. `repo-ci`. This is written to `spec.pipelineRef.name`.
65* Tekton `PipelineRun` name: generated by tack per trigger/workflow,
66 e.g. `tack-ci-yml-<short-hash>`. This is the concrete execution
67 object tack watches and stores.
68
69## Workflow YAML
70
71Only the provider and target pipeline are required:
72
73```yaml
74tack:
75 tekton:
76 pipeline: repo-ci
77```
78
79Optional fields:
80
81```yaml
82tack:
83 tekton:
84 pipeline: repo-ci
85 service_account: pipeline-runner
86 params:
87 image: example/app
88```
89
90`params` are forwarded as string Tekton params. Tack also stores the
91knot, pipeline rkey, workflow name, actor DID, commit, and branch as
92`PipelineRun` annotations, so operators can inspect the Kubernetes
93object and connect it back to the Tangled trigger.
94
95## Example Pipeline
96
97```yaml
98apiVersion: tekton.dev/v1
99kind: Pipeline
100metadata:
101 name: repo-ci
102 namespace: ci
103spec:
104 params:
105 - name: image
106 type: string
107 tasks:
108 - name: test
109 taskSpec:
110 params:
111 - name: image
112 type: string
113 steps:
114 - name: test
115 image: golang:1.25
116 script: |
117 set -eu
118 echo "building $(params.image)"
119 go test ./...
120 workspaces: []
121 params:
122 - name: image
123 value: $(params.image)
124```
125
126Detailed CI behavior belongs in the in-cluster `Pipeline`. The Tangled
127workflow YAML should stay small: select `tekton`, pick the target
128pipeline, and pass only the small set of params that pipeline expects.