Configuration Reference
The relay reads a single YAML file (default /etc/tekton-events-relay/config.yaml, mounted by the Helm chart from a ConfigMap). Validate any file without starting the server:
tekton-events-relay --validate --config ./config.yaml${UPPERCASE_VARS} are expanded from the environment for non-secret values. Secrets are always file-based (*_file keys pointing at mounted Secret volumes). Most sections can be hot-reloaded; server, store, dlq, logging and tracing need a restart.
A complete annotated example lives at examples/config.yaml.
Top level
| Key | Default | Description |
|---|---|---|
dashboard_url | — | Tekton Dashboard base URL; when set, events get a clickable TargetURL (…/#/namespaces/<ns>/<kind>/<run>). |
dedupe_size | 10000 | Capacity of the in-memory dedupe cache (store.backend: memory only). |
max_concurrency | 100 | Max handlers executing concurrently per event (1–500). |
handler_timeout | 10s | Per-handler execution deadline; a slow provider can’t stall the dispatch. |
server
| Key | Default | Description |
|---|---|---|
addr | :8080 | Receiver listen address. |
metrics_addr | — | Optional separate metrics/health server (e.g. :9090). |
read_timeout_sec / write_timeout_sec | 10 / 10 | HTTP timeouts. |
shutdown_timeout_sec | 30 | Graceful shutdown budget. |
max_body_size | 1048576 | Request body cap in bytes. |
rate_limit.enabled | false | Per-source token bucket (keyed by Ce-Source, falls back to client IP). |
rate_limit.requests_per_second / burst | 100 / 200 | Bucket parameters. |
auth.enabled | false | Authenticate incoming CloudEvents. |
auth.type | — | hmac-sha256 (GitHub-style X-Hub-Signature-256) or bearer. |
auth.secretRef.name | — | Kubernetes Secret name containing the shared secret/token. |
auth.secretRef.key | — | Key within the Secret (optional; defaults to the conventional key). |
auth.validate_timestamp | true for HMAC | Replay protection: require X-Webhook-Timestamp (unix seconds) within tolerance. Required when auth.type is hmac-sha256; omit for bearer. |
auth.timestamp_tolerance | 5m | Accepted clock skew for replay protection. |
tls.cert_file / tls.key_file | — | Serve HTTPS natively (both required). Empty = plain HTTP behind your ingress. |
retry — outbound HTTP policy
Applies to all SCM clients and notifiers. Exponential backoff with jitter; Retry-After on 429/503 is honored (capped at max_backoff); 4xx other than 429 never retries.
| Key | Default |
|---|---|
retry.max_attempts | 4 (total, including the first request) |
retry.initial_backoff | 250ms |
retry.max_backoff | 30s |
store — state backend
Shared by the deduper and the accumulator. See Operations → State backends for choosing one.
| Key | Default | Description |
|---|---|---|
store.backend | memory | memory (per-pod), valkey (external RESP server), olric (embedded distributed cache). |
store.ttl | 1h | Entry lifetime on remote backends. |
store.valkey.address | — | host:port, required for valkey. |
store.valkey.password_file | — | Optional password file. |
store.valkey.db | 0 | Logical database. |
store.valkey.key_prefix | tekton-events-relay | Key namespace. |
store.olric.bind_port | 3320 | Data port between relay pods. |
store.olric.memberlist_port | 3322 | Gossip port (TCP+UDP). |
store.olric.peers | chart’s headless service | host:port seeds for discovery. |
⚠️ With
memory, dedup/accumulation state is per-pod and lost on restart — run one replica, or switch backends. Backend failures fail open: events are processed without deduplication rather than dropped (tekton_events_relay_store_errors_total).
dlq — dead letter queue
| Key | Default | Description |
|---|---|---|
dlq.enabled | false | Preserve permanently-failed events for inspection/replay (API). |
dlq.path | /var/lib/tekton-events-relay/dlq.jsonl | JSONL file (chart mounts a writable emptyDir). |
dlq.max_size_bytes | 10485760 | Oldest entries are dropped beyond this. |
filter
Coarse resource-type gate, before any handler runs: allow_taskrun, allow_pipelinerun, allow_customrun, allow_eventlistener, ignore_unknown (booleans). If both taskrun and pipelinerun are unset, the default is pipelineruns only, ignore unknown.
accumulator
Batches TaskRun events per PipelineRun and posts one summary PR comment when the run completes.
| Key | Default | Description |
|---|---|---|
accumulator.enabled | false | |
accumulator.ttl | 30s | How long an incomplete run’s tasks are buffered. |
accumulator.max_size | 100 | Max pipeline runs tracked simultaneously. |
accumulator.provider.name | — | Registered handler that posts the summary (a pr_comment instance; use mode: upsert there for converging summaries). |
accumulator.template | built-in table | Custom Go template (receives SummaryData). |
scm — provider instances
Each provider key holds a list of instances; multiple instances of the same provider can coexist. The instance name is what the scm.provider annotation must match. Common instance fields:
| Field | Description |
|---|---|
name, enabled | Identity and switch. |
base_url | API base URL (self-hosted; defaults to the SaaS endpoint where applicable). |
insecure_skip_verify | Skip TLS verification (avoid; prefer a custom CA). |
secretRef.name | Kubernetes Secret name containing credentials. |
secretRef.key | Key within the Secret (optional; defaults to the conventional key). |
template | Go template inline string OR object with configmapRef (see below). |
template.configmapRef.name | Kubernetes ConfigMap name containing message templates. Optional; defaults to tekton-events-relay-templates. |
template.configmapRef.key | Key within the ConfigMap holding the template. |
auth.* | Provider-specific — token file, OAuth2 client-credentials, GitHub App. See each provider page. |
actions[] | The list of actions for this instance. |
Per-action fields: name, type, enabled, when (CEL), template, mode (create/upsert for comments), context_per_task (commit_status), labels.add[] / labels.remove[] (label), filter.{tasks,pipelines,custom_runs,event_listeners}.{allow,deny} lists.
notifiers
Lists per channel: slack, teams, discord, pagerduty, datadog, webhook, grafana, sentry, email. All support name, enabled, when (CEL); message-based ones support template (inline string or configmapRef object). email additionally has a subject field with the same three template forms. Notifier credentials use field-specific refs (e.g. webhook_url.secretRef.name for Slack/Teams/Discord, integration_key.secretRef.name for PagerDuty, token.secretRef.name for Grafana/Sentry). Templates can be supplied inline, via template.configmapRef.{name,key} (name optional, defaults to tekton-events-relay-templates), or omitted to use the shipped default — see Templates → Supplying a template. Notifiers that require a template (email, grafana) have no in-code default; the chart fills the omitted case from configmap-templates.yaml. Details and auth per channel on the Notifiers page.
Per-channel extras: slack accepts mode (create/upsert, upsert needs a bot token) and thread_ts (reply in a thread); discord accepts mode (create/upsert); pagerduty accepts acknowledge_on_running (opt-in acknowledge while running); grafana accepts dashboard_uid and panel_id (optional annotation scoping; panel_id requires dashboard_uid); email accepts cc/bcc lists, reply_to, and an auth.xoauth2 + auth.token_file XOAUTH2 mode (mutually exclusive with the password).
OAuth2 (webhook, jira): the generic webhook and Jira support OAuth2 client credentials under auth.oauth2 (client_id/client_secret refs + token_url; webhook also needs auth.type: oauth2). The relay fetches the access token, sends it as Authorization: Bearer, and auto-refreshes it before expiry. grant_type defaults to client_credentials; refresh_token is also supported (seed a pre-obtained refresh_token — the relay exposes no redirect/ingress, so authorization_code cannot run in-relay). oauth2 requires token_url and is mutually exclusive with the static token/basic credentials of the same notifier. Grafana/Sentry/Slack/Discord/Datadog/PagerDuty are not OAuth2-capable here — their APIs use a service-account token / auth token / bot token / API key / routing key.
Secret re-read (webhook, grafana, sentry, jira): when not using OAuth2, these notifiers re-read the mounted secret file on every request, so rotating a Kubernetes Secret is picked up without restarting the pod (no hot reload needed for the secret value).
jira
Top-level list (sibling of scm and notifiers) of Jira integrations, each with base_url, optional api_version ("2" default plain-text, or "3" Atlassian Document Format), auth (email + token.secretRef, or auth.oauth2 client credentials), and actions of type comment or transition. The target issue comes from the jira.issue-key annotation. Comment templates use the shared template.configmapRef.name/template.configmapRef.key mechanism. See Notifiers → Jira.
logging and tracing
| Key | Default | Description |
|---|---|---|
logging.level | info | debug, info, warn, error (JSON output). |
logging.verbose.caller / http_calls / payloads | false | Extra detail — valid only with level: debug (validation enforces this). Payloads are redacted of known secret keys. |
tracing.endpoint | — | OTLP HTTP endpoint (e.g. otel-collector:4318). Empty = tracing off. |
tracing.service_name | tekton-events-relay | Reported service name. |
tracing.insecure | false | When false, uses HTTPS for OTLP export. Set to true for plaintext HTTP. |