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:**
```json
{
  "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:**
```bash
kubectl get pods -l eventlistener=gitea-listener -n innoventions
kubectl get svc el-gitea-listener -n innoventions
```

**2. Watch EventListener logs:**
```bash
kubectl logs -l eventlistener=gitea-listener -n innoventions -f
```

**3. Make a test commit:**
```bash
cd /path/to/repo
git commit --allow-empty -m "Test webhook trigger"
git push origin main
```

**4. Verify PipelineRun created:**
```bash
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:**
```bash
kubectl logs -l eventlistener=gitea-listener -n innoventions --tail=100
```

Look for:
- Incoming requests
- Secret validation failures
- TriggerBinding errors

2. **Verify webhook secret:**
```bash
# 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:**
```bash
# 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:**
```bash
kubectl describe pipelinerun -n innoventions PIPELINERUN-NAME
```

2. **Check task logs:**
```bash
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:

```yaml
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:

```yaml
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:

```yaml
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:**
```bash
# 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