tekton-events-relay

module
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 30, 2026 License: MIT

README

Tekton Events Relay

Your pipelines run. Your platforms get updated. You write zero notification code.

A production-ready CloudEvents bridge that turns Tekton pipeline events into commit statuses, PR comments, labels, deployments and alerts — across 6 SCM platforms and 10 notification channels — driven by annotations and CEL expressions instead of pipeline plumbing.

Release CodeQL Latest Release Artifact Hub Go Version Go Report Card License

📖 Documentation · ⚡ Quickstart · 🏗 Architecture · 📦 Helm Chart

The problem

Reporting CI status from Tekton means polluting every pipeline with notification Tasks, finally blocks, duplicated credentials and copy-pasted curl scripts. Multiply that by every repo, every provider, every chat channel — and pipeline YAML stops being about building software.

The fix

Tekton already emits a CloudEvent for every state change. The relay listens once, and your config decides what happens — your pipelines never change:

flowchart LR
    TK[Tekton Pipelines] -- CloudEvents --> R{{Tekton Events Relay}}
    R --> SCM[GitHub · GitLab · Gitea<br/>Bitbucket · Azure DevOps · SourceHut]
    R --> CHAT[Slack · Teams · Discord]
    R --> OPS[PagerDuty · Datadog · Grafana · Sentry]
    R --> HOOK[Generic Webhooks]

Annotate the PipelineRun once, in your TriggerTemplate:

metadata:
  annotations:
    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.pr-number: "$(tt.params.pr-number)"

…and declare outcomes in one place:

scm:
  github:
    - name: github
      enabled: true
      auth:
        secretRef:
          name: github-token
          key: token
      actions:
        - name: task-checks                # one required check per task
          type: commit_status
          enabled: true
          context_per_task: true
        - name: pr-summary                 # ONE comment that updates itself
          type: pr_comment
          enabled: true
          mode: upsert
          when: 'isPipelineRun() && stateIn("running", "success", "failure")'
        - name: ci-labels                  # declarative label lifecycle
          type: label
          enabled: true
          labels:
            add: ["ci::{{.State}}"]
            remove: ["ci::running", "ci::success", "ci::failure"]

notifiers:
  slack:
    - name: prod-alerts                    # only what's worth waking up for
      enabled: true
      webhook_url:
        secretRef:
          name: slack-webhook
          key: webhook_url
      channel: "#prod-alerts"
      when: 'event.Namespace == "production" && stateIn("failure", "error")'

Secret mounting pattern: Helm values secretRef references are mounted as files at /etc/secrets/{provider}/{instance}/{key} and rendered into the relay config *_file fields automatically.

What it speaks

Action GitHub GitLab Gitea Bitbucket Azure DevOps SourceHut
commit_status (+ per-task checks) ✅ ✅ ✅ ✅ ✅ ✅
pr_comment — idempotent upsert ✅ ✅ ✅ ✅* ✅ —
commit_comment (pushes without PR) ✅ ✅ — — — —
issue_comment / discussion_comment ✅ / ✅ ✅ / ✅† ✅ / — — — —
check_run (rich markdown checks) ✅ — — — — —
deployment_status (Environments) ✅ ✅ — — — —
label — declarative add/remove ✅ ✅ ✅ — ✅ —

* upsert on Cloud; Server falls back to create. † GitLab discussion_comment posts a resolvable MR discussion thread (MR-only). Plus notifiers: Slack, Microsoft Teams, Discord, PagerDuty, Datadog, Grafana deploy annotations, Sentry releases, and generic webhooks with gojq payload transforms (DevLake, anyone?).

Built like infrastructure, not a script
🔁 Self-updating comments mode: upsert embeds an invisible marker and edits the same comment as the run progresses — idempotent across retries, restarts and replicas.
🧠 Routing as expressions Every action/notifier is gated by CEL: event.Namespace == "production" && stateIn("failure"). Macros included (isPR(), stateIn(…)).
🗃 Multi-replica correctness Pluggable state backends — in-memory, Valkey, or embedded Olric (zero extra deployments) — keep dedup and batching correct at scale.
📮 Nothing lost 429/5xx → retries with jitter honoring Retry-After; overload → 503 back-pressure (Tekton retransmits); permanent failures → dead letter queue with one-call replay.
♻️ Hot reload ConfigMap/secret changes apply without restart — validated first, swapped atomically, counted in metrics.
🔭 Observable 20+ Prometheus metrics, OpenTelemetry traces per handler, and a /readyz that tells you which provider is failing and why.
🔐 Hardened HMAC webhook auth with replay protection, native TLS, rate limiting, distroless non-root image, Cosign-signed releases.

Quickstart

kubectl create secret generic github-token -n tekton-events-relay \
  --from-literal=token="ghp_..." --dry-run=client -o yaml | kubectl apply -f -

helm install tekton-events-relay \
  oci://ghcr.io/fabioluciano/charts/tekton-events-relay \
  --namespace tekton-events-relay --create-namespace \
  -f values.yaml

Point Tekton's default-cloud-events-sink at the relay Service, annotate your runs, done. Full walkthrough → wiki/Quickstart

Documentation

Everything lives in the wiki: Installation · Annotations contract · Configuration reference · Actions · Templates · Operations · Observability · Troubleshooting · Examples

Why not just…?

Alternative The catch
Notification Tasks + finally in each pipeline N× duplicated logic and credentials; pipelines stop being about building. The relay is one deployment and zero pipeline changes.
Your SCM's native CI Then you're not on Tekton. If you are, this is the missing feedback layer.
A quick webhook script Congratulations, you now own retries, rate limits, dedup, secrets, HA and metrics. That's this project — already tested.

Security & supply chain

All images and charts are Cosign-signed (keyless OIDC, recorded in Rekor):

cosign verify \
  --certificate-identity-regexp='https://github.com/fabioluciano/tekton-events-relay' \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
  ghcr.io/fabioluciano/tekton-events-relay:latest

Found a vulnerability? Please follow the responsible disclosure policy.

Contributing

PRs welcome — see CONTRIBUTING.md and the release flow. Releases are fully automated with semantic-release; Conventional Commits required.

License

MIT

Directories

Path Synopsis
cmd
receiver command
Package main provides the tekton-events-relay receiver service that listens for CloudEvents and dispatches notifications to configured destinations.
 Package main provides the tekton-events-relay receiver service that listens for CloudEvents and dispatches notifications to configured destinations.
internal
accumulator
Package accumulator provides a concurrent-safe buffer for aggregating TaskRun events by PipelineRun UID, enabling pipeline summary comments.
 Package accumulator provides a concurrent-safe buffer for aggregating TaskRun events by PipelineRun UID, enabling pipeline summary comments.
cehttp
Package cehttp provides CloudEvents parsing using the official SDK.
 Package cehttp provides CloudEvents parsing using the official SDK.
cel
Package cel provides CEL expression compilation and evaluation against domain.Event.
 Package cel provides CEL expression compilation and evaluation against domain.Event.
config
Package config provides configuration loading and management for tekton-events-relay.
 Package config provides configuration loading and management for tekton-events-relay.
dlq
Package dlq implements a dead letter queue for events that failed with permanent (non-retryable) errors.
 Package dlq implements a dead letter queue for events that failed with permanent (non-retryable) errors.
domain
Package domain defines the neutral event model, independent of any notifier or decoder.
 Package domain defines the neutral event model, independent of any notifier or decoder.
errors
Package errors provides error classification and handling utilities.
 Package errors provides error classification and handling utilities.
event
Package event defines the types shared between decoders (Strategy) and the registry that resolves which decoder to use for each CloudEvent.
 Package event defines the types shared between decoders (Strategy) and the registry that resolves which decoder to use for each CloudEvent.
event/tekton
Package tekton implements the Decoder for CloudEvents emitted by tekton-events-controller.
 Package tekton implements the Decoder for CloudEvents emitted by tekton-events-controller.
factory
Package factory provides a generic factory pattern for building ActionHandlers from typed configuration structs, eliminating runtime type assertions.
 Package factory provides a generic factory pattern for building ActionHandlers from typed configuration structs, eliminating runtime type assertions.
http
Package http provides the HTTP handler and server for the tekton-events-relay receiver.
 Package http provides the HTTP handler and server for the tekton-events-relay receiver.
http/middleware
Package middleware provides HTTP middleware for authentication, rate limiting, and body limits.
 Package middleware provides HTTP middleware for authentication, rate limiting, and body limits.
httpx
Package httpx contains HTTP utilities for unified client behavior.
 Package httpx contains HTTP utilities for unified client behavior.
logging
Package logging provides zap logger configuration and factory.
 Package logging provides zap logger configuration and factory.
metrics
Package metrics provides Prometheus metrics collectors and HTTP middleware.
 Package metrics provides Prometheus metrics collectors and HTTP middleware.
notifier
Package notifier defines the common Strategy interface for all notification destinations (SCM, Slack, Teams, Discord, PagerDuty, Datadog, Webhook) and the Registry that resolves which notifiers to call for each event.
 Package notifier defines the common Strategy interface for all notification destinations (SCM, Slack, Teams, Discord, PagerDuty, Datadog, Webhook) and the Registry that resolves which notifiers to call for each event.
notifier/batch
Package batch provides a generic message batching wrapper for ActionHandlers.
 Package batch provides a generic message batching wrapper for ActionHandlers.
notifier/datadog
Package datadog implements the Notifier for Datadog via Events API v2.
 Package datadog implements the Notifier for Datadog via Events API v2.
notifier/discord
Package discord implements the Notifier for Discord via the discordgo SDK.
 Package discord implements the Notifier for Discord via the discordgo SDK.
notifier/email
Package email implements the Notifier for SMTP delivery via the github.com/wneessen/go-mail SDK.
 Package email implements the Notifier for SMTP delivery via the github.com/wneessen/go-mail SDK.
notifier/grafana
Package grafana posts deployment markers to the Grafana Annotations API, so pipeline events appear as vertical markers on dashboards.
 Package grafana posts deployment markers to the Grafana Annotations API, so pipeline events appear as vertical markers on dashboards.
notifier/honeycomb
Package honeycomb implements the Notifier for Honeycomb via the Events API.
 Package honeycomb implements the Notifier for Honeycomb via the Events API.
notifier/incidentio
Package incidentio implements the Notifier for Incident.io via the v2 Incidents API.
 Package incidentio implements the Notifier for Incident.io via the v2 Incidents API.
notifier/jira
Package jira implements issue-tracking actions against Jira Cloud and Data Center: commenting on issues and transitioning their status when pipeline events arrive.
 Package jira implements issue-tracking actions against Jira Cloud and Data Center: commenting on issues and transitioning their status when pipeline events arrive.
notifier/kafka
Package kafka implements a notifier that publishes pipeline events to Apache Kafka.
 Package kafka implements a notifier that publishes pipeline events to Apache Kafka.
notifier/mattermost
Package mattermost implements the Notifier for Mattermost.
 Package mattermost implements the Notifier for Mattermost.
notifier/middleware
Package middleware provides reusable handler wrappers for CEL guards and filters.
 Package middleware provides reusable handler wrappers for CEL guards and filters.
notifier/msgstore
Package msgstore persists a single message reference (e.g.
 Package msgstore persists a single message reference (e.g.
notifier/nats
Package nats implements a notifier that publishes pipeline events to NATS.
 Package nats implements a notifier that publishes pipeline events to NATS.
notifier/newrelic
Package newrelic implements the Notifier for New Relic via the Event API.
 Package newrelic implements the Notifier for New Relic via the Event API.
notifier/opsgenie
Package opsgenie implements the Notifier for Opsgenie via Alert API v2.
 Package opsgenie implements the Notifier for Opsgenie via Alert API v2.
notifier/pagerduty
Package pagerduty implements the Notifier for PagerDuty via Events API v2.
 Package pagerduty implements the Notifier for PagerDuty via Events API v2.
notifier/rabbitmq
Package rabbitmq implements a notifier that publishes pipeline events to RabbitMQ.
 Package rabbitmq implements a notifier that publishes pipeline events to RabbitMQ.
notifier/redispubsub
Package redispubsub implements a notifier that publishes pipeline events to a Redis Pub/Sub channel.
 Package redispubsub implements a notifier that publishes pipeline events to a Redis Pub/Sub channel.
notifier/scm
Package scm provides SCM provider integrations for commit status, comments, and labels.
 Package scm provides SCM provider integrations for commit status, comments, and labels.
notifier/scm/azuredevops
Package azuredevops provides Azure DevOps SCM notifier client.
 Package azuredevops provides Azure DevOps SCM notifier client.
notifier/scm/bitbucket
Package bitbucket provides Bitbucket Cloud and Server SCM notifier clients.
 Package bitbucket provides Bitbucket Cloud and Server SCM notifier clients.
notifier/scm/gitea
Package gitea provides Gitea SCM integration for the relay.
 Package gitea provides Gitea SCM integration for the relay.
notifier/scm/github
Package github provides GitHub SCM integrations for commit status, check runs, comments, and labels.
 Package github provides GitHub SCM integrations for commit status, check runs, comments, and labels.
notifier/scm/gitlab
Package gitlab provides GitLab SCM notifier client.
 Package gitlab provides GitLab SCM notifier client.
notifier/scm/oauth2
Package oauth2 provides OAuth2 token clients for the grants the relay can perform headlessly (no inbound redirect): client_credentials and refresh_token.
 Package oauth2 provides OAuth2 token clients for the grants the relay can perform headlessly (no inbound redirect): client_credentials and refresh_token.
notifier/scm/sourcehut
Package sourcehut provides SourceHut SCM notifier client.
 Package sourcehut provides SourceHut SCM notifier client.
notifier/sentry
Package sentry creates Sentry releases and deploy markers from pipeline events, associating errors with the deployed version (the CommitSHA).
 Package sentry creates Sentry releases and deploy markers from pipeline events, associating errors with the deployed version (the CommitSHA).
notifier/slack
Package slack implements the Notifier for Slack.
 Package slack implements the Notifier for Slack.
notifier/teams
Package teams implements the Notifier for Microsoft Teams via Incoming Webhooks.
 Package teams implements the Notifier for Microsoft Teams via Incoming Webhooks.
notifier/telegram
Package telegram implements the Notifier for Telegram via the Bot API.
 Package telegram implements the Notifier for Telegram via the Bot API.
notifier/webhook
Package webhook implements a generic Notifier via HTTP.
 Package webhook implements a generic Notifier via HTTP.
pipeline
Package pipeline implements Chain of Responsibility for processing CloudEvent events received from Tekton.
 Package pipeline implements Chain of Responsibility for processing CloudEvent events received from Tekton.
secrets
Package secrets provides utilities for resolving secret references.
 Package secrets provides utilities for resolving secret references.
store
Package store defines pluggable state backends for deduplication and event accumulation, so multi-replica deployments can share state.
 Package store defines pluggable state backends for deduplication and event accumulation, so multi-replica deployments can share state.
tracing
Package tracing provides OpenTelemetry distributed tracing setup for tekton-events-relay.
 Package tracing provides OpenTelemetry distributed tracing setup for tekton-events-relay.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.