Configuration Reference

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.secret_file	—	File containing the shared secret/token.
auth.validate_timestamp	false	Replay protection: require X-Webhook-Timestamp (unix seconds) within tolerance. HMAC only.
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).
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. All support name, enabled, when (CEL); message-based ones support template. Details and auth per channel on the Notifiers page.

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.