Quickstart

Quickstart

Get from zero to a GitHub commit status in about 10 minutes. The same flow applies to every provider — see the per-provider pages for variations.

Prerequisites

• Kubernetes 1.24+, Helm 3.8+
• Tekton Pipelines v0.40+ with CloudEvents emission enabled
• A GitHub personal access token with repo:status scope

1. Create the provider secret

kubectl create namespace tekton-events-relay

kubectl create secret generic github-token \
  --namespace tekton-events-relay \
  --from-literal=token="ghp_your_personal_access_token"

2. Install the relay

helm install tekton-events-relay \
  oci://ghcr.io/fabioluciano/charts/tekton-events-relay \
  --namespace tekton-events-relay \
  --set 'config.scm.github[0].name=github' \
  --set 'config.scm.github[0].enabled=true' \
  --set 'config.scm.github[0].auth.secretRef.name=github-token' \
  --set 'config.scm.github[0].actions[0].name=commit-status' \
  --set 'config.scm.github[0].actions[0].type=commit_status' \
  --set 'config.scm.github[0].actions[0].enabled=true'

The instance name (github here) is what your PipelineRuns will reference in the scm.provider annotation — they must match exactly.

For anything beyond a demo, use a values file instead of --set. See Installation.

3. Check the relay is healthy

Before touching Tekton, confirm the relay is up and the handler is registered:

kubectl exec -n tekton-events-relay deploy/tekton-events-relay -- \
  wget -qO- localhost:8080/readyz

You should see the github instance listed as ready. If the pod is CrashLooping, validate your config first — see Troubleshooting → Config & deploy issues.

4. Point Tekton at the relay

Tell the Tekton Pipelines controller to send CloudEvents to the relay's Service (edit the config-defaults ConfigMap in tekton-pipelines):

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-cloud-events-sink: http://tekton-events-relay.tekton-events-relay.svc.cluster.local

5. Annotate your PipelineRun

The relay only acts on runs that carry its annotations. In a TriggerTemplate this is one block, filled from the webhook payload:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: ci-run-
  annotations:
    # must match the instance name from step 2
    tekton.dev/tekton-events-relay.scm.provider: "github"
    tekton.dev/tekton-events-relay.scm.repo-owner: "my-org"
    tekton.dev/tekton-events-relay.scm.repo-name: "my-repo"
    tekton.dev/tekton-events-relay.scm.commit-sha: "$(tt.params.revision)"
    tekton.dev/tekton-events-relay.scm.context: "tekton/ci"
spec:
  pipelineRef:
    name: ci-pipeline

6. Run a pipeline and watch

Trigger the pipeline. Within seconds of each state change you should see the commit status on GitHub flip from pending → success/failure.

If nothing shows up:

kubectl logs -n tekton-events-relay deploy/tekton-events-relay -f

and check the Troubleshooting guide — the two most common causes are a missing scm.provider annotation and the CloudEvents sink not being configured.

Next steps

• Filter what triggers what with CEL expressions
• Add Slack/Teams notifications for failures only
• Make PR comments idempotent with mode: upsert
• Going multi-replica? Read Operations → State backends first