Annotations

Annotations

Annotations are the integration contract between your pipelines and the relay. They are plain Kubernetes annotations on the PipelineRun/TaskRun, normally set once in your TriggerTemplate from webhook payload values — your pipelines themselves never change.

All keys live under the tekton.dev/tekton-events-relay. prefix.

Minimum set per action

What each action type needs, at a glance (keys shown without the prefix):

Action	scm.provider	repo coordinates¹	scm.commit-sha	scm.pr-number	scm.issue-number	scm.discussion-number
commit_status	✅	✅	✅	—	—	—
commit_comment	✅	✅	✅	—	—	—
check_run	✅	✅	✅	—	—	—
pr_comment	✅	✅	—	✅	—	—
label (on a PR)	✅	✅	—	✅	—	—
label (on an issue)	✅	✅	—	—	✅	—
issue_comment	✅	✅	—	—	✅	—
discussion_comment	✅	✅	—	—	—	✅
deployment_status	✅	✅	✅	—	—	—

¹ Repo coordinates vary per provider: GitHub / Gitea / SourceHut use repo-owner + repo-name; GitLab uses repo-owner + repo-name or repo-id; Bitbucket Cloud uses repo-workspace + repo-name; Bitbucket Server uses repo-project + repo-name; Azure DevOps uses repo-org + repo-project + repo-name.

scm.context is optional everywhere — it names the check (e.g. tekton/ci) and doubles as the environment name for deployment_status.

Reference

Annotation	Required	Used by	Description
tekton.dev/tekton-events-relay.scm.provider	yes (for SCM actions)	all SCM	Which configured SCM instance handles this run. Must match an instance name from your config (e.g. github, gitlab-main). Events without it are skipped by SCM handlers.
tekton.dev/tekton-events-relay.scm.commit-sha	yes for commit_status, commit_comment, check_run	all SCM	The commit being built.
tekton.dev/tekton-events-relay.scm.repo-owner	provider-dependent	GitHub, Gitea, GitLab, SourceHut	Repository owner / org / user.
tekton.dev/tekton-events-relay.scm.repo-name	provider-dependent	all SCM	Repository name.
tekton.dev/tekton-events-relay.scm.repo-id	alternative	GitLab	Numeric project ID (alternative to owner+name).
tekton.dev/tekton-events-relay.scm.repo-workspace	provider-dependent	Bitbucket Cloud	Workspace slug.
tekton.dev/tekton-events-relay.scm.repo-project	provider-dependent	Bitbucket Server, Azure DevOps	Project key/name.
tekton.dev/tekton-events-relay.scm.repo-org	provider-dependent	Azure DevOps	Organization.
tekton.dev/tekton-events-relay.scm.pr-number	for PR actions	all SCM	Pull/merge request number. Enables pr_comment, label, merge-style actions.
tekton.dev/tekton-events-relay.scm.issue-number	for issue actions	GitHub, Gitea	Issue number for issue_comment / label.
tekton.dev/tekton-events-relay.scm.discussion-number	for discussions	GitHub	Discussion number for discussion_comment.
tekton.dev/tekton-events-relay.scm.context	no	all SCM	Logical check name (e.g. tekton/ci). Also used as the environment name by deployment actions. Default behavior varies per action.
tekton.dev/tekton-events-relay.scm.api-base-url	no	all SCM	Per-run API base URL override (self-hosted instances).
tekton.dev/tekton-events-relay.jira.issue-key	for Jira actions	Jira	Issue key (e.g. PROJ-123) the comment / transition actions act on. Extracted by the TriggerBinding from the branch name or PR/MR title.

Wiring annotations in a TriggerTemplate

The values come straight from the webhook interceptor params:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: github-pr
spec:
  params:
    - name: repo-owner
    - name: repo-name
    - name: revision
    - name: pr-number
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: pr-ci-
        annotations:
          tekton.dev/tekton-events-relay.scm.provider: "github"
          tekton.dev/tekton-events-relay.scm.repo-owner: "$(tt.params.repo-owner)"
          tekton.dev/tekton-events-relay.scm.repo-name: "$(tt.params.repo-name)"
          tekton.dev/tekton-events-relay.scm.commit-sha: "$(tt.params.revision)"
          tekton.dev/tekton-events-relay.scm.pr-number: "$(tt.params.pr-number)"
          tekton.dev/tekton-events-relay.scm.context: "tekton/ci"
      spec:
        pipelineRef:
          name: ci-pipeline

And the matching TriggerBinding for a GitHub pull request webhook:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: github-pr
spec:
  params:
    - name: repo-owner
      value: $(body.repository.owner.login)
    - name: repo-name
      value: $(body.repository.name)
    - name: revision
      value: $(body.pull_request.head.sha)
    - name: pr-number
      value: $(body.pull_request.number)

How annotations reach TaskRuns

Tekton propagates PipelineRun annotations to its child TaskRuns, so per-task events (e.g. with context_per_task) carry the same routing information automatically. You annotate once, at PipelineRun creation.

Design rule

The relay deliberately never requires changes inside pipelines — no extra Tasks, steps, sidecars or results. If a feature needs an input your pipeline doesn't naturally produce, the answer is always an annotation set at trigger time, or data the CloudEvent already carries (state, timestamps, commit SHA, Tekton results that already exist).