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