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.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	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).
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.

jira

Top-level list (sibling of scm and notifiers) of Jira integrations, each with base_url, auth (email + token.secretRef), 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.