homelab/cluster/tekton/triggers/README.md

Tekton Triggers Library

Webhook integration for automatic pipeline execution from Git events.

---

Overview

Tekton Triggers enable event-driven CI/CD by listening for webhooks from Git providers (Gitea, GitHub, GitLab) and automatically starting pipeline runs.

Components:

• EventListener - HTTP endpoint that receives webhooks
• TriggerBinding - Extracts data from webhook payload
• TriggerTemplate - Creates PipelineRun from extracted data

Flow:

Git Push → Gitea Webhook → EventListener → TriggerBinding → TriggerTemplate → PipelineRun

---

Available Triggers

gitea-listener (EventListener)

HTTP service that receives webhooks from Gitea.

Endpoint: http://el-gitea-listener.innoventions.svc.cluster.local:8080

Supported events:

• Push (branch commits)
• Tag creation (future)
• Pull request (future)

Security:

• Validates webhook secret from 1Password
• Only processes push events
• Uses Gitea interceptor for payload validation

---

gitea-binding (TriggerBinding)

Extracts information from Gitea webhook payload.

Extracted parameters:

• git-repo-url - Repository clone URL
• git-revision - Commit SHA
• repo-name - Repository name (for image naming)

Gitea webhook payload structure:

{
  "repository": {
    "clone_url": "https://gitea.mk-labs.cloud/rblundon/my-app.git",
    "name": "my-app"
  },
  "after": "abc123def456...",
  "ref": "refs/heads/main"
}

---

gitea-template (TriggerTemplate)

Creates a PipelineRun when webhook is received.

What it creates:

• PipelineRun with generateName (unique per trigger)
• Parameters from TriggerBinding
• Workspace using volumeClaimTemplate (auto-created)

Image naming convention:

• Target: the-seas.local.mk-labs.cloud/library/REPO-NAME
• Tag: Git commit SHA (enables traceability)

---

Configuring Gitea Webhooks

Per-repository setup:

1. Navigate to repository in Gitea

2. Settings → Webhooks → Add Webhook → Gitea

3. Configure:

   • URL: http://el-gitea-listener.innoventions.svc.cluster.local:8080
   • HTTP Method: POST
   • Content Type: application/json
   • Secret: (get from 1Password vault innoventions, field gitea-webhook-secret)
   • Trigger On: Push events
   • Branch filter: (leave empty for all branches, or specify like main)
   • Active: ✓ Enabled

4. Click "Add Webhook"

5. Test with "Test Delivery" button

Webhook URL alternatives:

• Inside cluster: http://el-gitea-listener.innoventions.svc.cluster.local:8080
• Via Gateway (if exposed): TBD in future phase

---

Testing Webhook Integration

1. Check EventListener is running:

kubectl get pods -l eventlistener=gitea-listener -n innoventions
kubectl get svc el-gitea-listener -n innoventions

2. Watch EventListener logs:

kubectl logs -l eventlistener=gitea-listener -n innoventions -f

3. Make a test commit:

cd /path/to/repo
git commit --allow-empty -m "Test webhook trigger"
git push origin main

4. Verify PipelineRun created:

kubectl get pipelinerun -n innoventions -w

5. Check webhook delivery in Gitea:

• Repository → Settings → Webhooks → Click webhook
• View "Recent Deliveries" tab
• Should show 200 OK response

---

Debugging Webhooks

Webhook not triggering:

1. Check EventListener logs:

kubectl logs -l eventlistener=gitea-listener -n innoventions --tail=100

Look for:

• Incoming requests
• Secret validation failures
• TriggerBinding errors

2. Verify webhook secret:

# Get secret from Kubernetes
kubectl get secret gitea-webhook-secret -n innoventions -o jsonpath='{.data.secret}' | base64 -d

# Compare with 1Password vault `innoventions` field

3. Check Gitea webhook deliveries:

• Green checkmark = successful
• Red X = failed
• Click delivery to see request/response details

4. Test EventListener directly:

# From within cluster
kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
  curl -X POST http://el-gitea-listener.innoventions.svc.cluster.local:8080 \
  -H "Content-Type: application/json" \
  -H "X-Gitea-Event: push" \
  -d '{"repository":{"clone_url":"https://gitea.mk-labs.cloud/rblundon/test.git","name":"test"},"after":"abc123"}'

PipelineRun created but fails:

1. Check PipelineRun details:

kubectl describe pipelinerun -n innoventions PIPELINERUN-NAME

2. Check task logs:

tkn pipelinerun logs PIPELINERUN-NAME -n innoventions

3. Common issues:

• Git clone fails: Check Gitea connectivity, credentials
• Image build fails: Check Dockerfile syntax
• Image push fails: Check Harbor credentials

---

Customizing Triggers

Add Tag Triggers

Create separate trigger for Git tags:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: gitea-listener
spec:
  triggers:
    - name: gitea-push
      # ... existing push trigger
    
    - name: gitea-tag
      interceptors:
        - ref:
            name: gitea
          params:
            - name: secretRef
              value:
                secretName: gitea-webhook-secret
                secretKey: secret
            - name: eventTypes
              value:
                - create  # Tag creation
      bindings:
        - ref: gitea-tag-binding
      template:
        ref: gitea-tag-template

Filter by Branch

Only trigger on specific branches:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
spec:
  triggers:
    - name: gitea-main-branch
      interceptors:
        - ref:
            name: gitea
        - ref:
            name: cel
          params:
            - name: filter
              value: "body.ref == 'refs/heads/main'"
      # ... rest of config

Custom Image Tagging

Modify TriggerTemplate to use semantic versioning:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
spec:
  params:
    - name: git-revision
    - name: repo-name
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      spec:
        params:
          - name: image-tag
            value: "$(tt.params.git-revision)-$(date +%Y%m%d-%H%M%S)"

---

Security Considerations

Webhook secret validation:

• ALWAYS use webhook secrets
• Rotate secrets periodically
• Store in 1Password, sync via ExternalSecret

Network policies:

• EventListener only accessible from Gitea
• Consider adding NetworkPolicy to restrict access

RBAC:

• EventListener ServiceAccount has minimal permissions
• Can only create PipelineRuns in innoventions namespace

Resource limits:

• Consider rate limiting in future (max runs per hour)
• Set PipelineRun timeouts to prevent runaway builds

---

Monitoring & Observability

EventListener metrics:

# Prometheus metrics endpoint
kubectl port-forward svc/el-gitea-listener 8080:8080 -n innoventions
curl http://localhost:8080/metrics

Key metrics:

• eventlistener_triggered_total - Total webhooks processed
• eventlistener_event_count - Events by type
• tekton_pipelinerun_duration_seconds - Build duration

Logs aggregation:

• EventListener logs show webhook receipt
• PipelineRun logs show build execution
• Consider centralizing logs (Loki/ELK in future)

---

Advanced Patterns

Multi-pipeline triggers: Trigger different pipelines based on event type:

• Push to main → Production build
• Push to dev → Development build
• PR created → Test run only

Conditional execution: Use CEL interceptors to filter:

• Only build if Dockerfile changed
• Skip builds for doc-only commits
• Build specific services in monorepo

Fan-out builds: One webhook triggers multiple pipelines:

• Build multiple architectures
• Build and deploy to multiple environments
• Run parallel test suites

---

References

Tekton Triggers Docs:

• EventListeners: https://tekton.dev/docs/triggers/eventlisteners/
• TriggerBindings: https://tekton.dev/docs/triggers/triggerbindings/
• TriggerTemplates: https://tekton.dev/docs/triggers/triggertemplates/
• Interceptors: https://tekton.dev/docs/triggers/interceptors/

Gitea Webhook Docs:

• https://docs.gitea.io/en-us/webhooks/

Examples:

• https://github.com/tektoncd/triggers/tree/main/examples

---

Location: cluster/tekton/triggers/
Deployed to: innoventions namespace
Owner: Platform Team