Actions

Actions

Actions are what an SCM instance does when an event matches. Each action is declared under its instance's actions: list, and every action is independently gated by its own when CEL expression and optional name filters.

scm:
  github:
    - name: github          # ← matched by the scm.provider annotation
      enabled: true
      auth:
        secretRef:
          name: github-token
      actions:
        - name: ci-status
          type: commit_status
          enabled: true
          when: 'isPipelineRun()'
        - name: pr-summary
          type: pr_comment
          enabled: true
          mode: upsert
          when: 'isPipelineRun() && stateIn("success", "failure")'
          template: |
            ## Pipeline {{.State}}
            **Run:** {{.RunName}} · **Commit:** `{{.CommitSHA}}`
            {{if .TargetURL}}[Logs]({{.TargetURL}}){{end}}

Availability per provider: see the capability matrix.

commit_status

Sets the commit/PR status (the check that branch protection can require). Uses the scm.context annotation as the check name. Tekton states map per provider (e.g. running → pending on GitHub/Gitea, INPROGRESS on Bitbucket).

Granular per-task statuses (context_per_task)

- name: ci-status
  type: commit_status
  enabled: true
  context_per_task: true

With context_per_task: true, TaskRun events report under <context>/<task> (e.g. tekton/ci/build, tekton/ci/test) instead of one shared context — so branch protection can require exactly the checks that matter. PipelineRun events keep the plain context.

Comments: pr_comment, issue_comment, discussion_comment, commit_comment

All render a Go template and post it:

• pr_comment — needs the scm.pr-number annotation.
• issue_comment — needs scm.issue-number (GitHub, Gitea, GitLab).
• discussion_comment — needs scm.discussion-number (GitHub, via GraphQL). GitLab posts a resolvable MR discussion thread and needs scm.pr-number (MR-only).
• commit_comment — comments on the commit itself; covers direct pushes where no PR exists (GitHub, GitLab). Needs only scm.commit-sha.

Comment templates are optional

The comment template is optional for every SCM provider. Supply it three ways:

# 1. Inline string
template: |
  ## Pipeline {{.State}}
  **Run:** {{.RunName}}

# 2. From a ConfigMap (the chart ships rich defaults you can point at)
template:
  configmapRef:
    name: tekton-events-relay-templates   # optional; this is the default
    key: github-pr-comment.tmpl

# 3. Omitted — the relay posts a minimal built-in body: "Build <State> for <RunName>"

Unlike email and grafana (which require a template), omitting an SCM comment template is valid and falls back to the built-in body — it is never an error. The shipped *.tmpl keys (github-pr-comment.tmpl, gitlab-note.tmpl, gitea-pr-comment.tmpl, azuredevops-comment.tmpl, …) are opt-in examples wired via configmapRef, not auto-applied. See Templates → Supplying a template.

Idempotent comments (mode: upsert)

- name: pr-summary
  type: pr_comment
  mode: upsert        # default: create

In upsert mode the relay embeds an invisible HTML marker (<!-- tekton-events-relay:<run-uid>:<action> -->) in the comment and, on later events for the same run, edits that comment instead of posting a new one. This makes comments idempotent across Tekton retransmissions, pod restarts and multiple replicas — the dedup state lives in the PR itself. A running→success transition produces one comment that updates in place.

Supported: GitHub, GitLab, Gitea, Azure DevOps, Bitbucket Cloud, and issue_comment/discussion_comment/commit_comment where available. Bitbucket Server falls back to create (a startup warning is logged). If listing existing comments fails, the relay falls back to creating one — an API hiccup never blocks the notification.

label

Declarative label management on the PR/issue with optional color control. The action's when is the only trigger; the action itself just declares the effect:

- name: ci-labels
  type: label
  enabled: true
  when: 'event.Resource == "pipelinerun"'
  labels:
    add:
      - name: "ci:passed"
        color: "0e8a16"      # green (hex without #)
      - name: "ready-to-merge"
        # color omitted = provider default
    remove:
      - name: "ci:failed"

Label Colors:

• Format: 6-character hex without # prefix (e.g., d73a4a for red, 0e8a16 for green, 1d76db for blue)
• Optional: Omit color field or leave empty to use provider default
• Invalid colors: Logged as warnings and fall back to provider default
• Existing labels: Color is preserved (idempotent) — only missing labels are created with specified color

Provider Behavior:

• GitHub: Creates missing labels via repo API with specified color; empty color uses random pastel
• GitLab: Creates missing labels with color before applying (default: #428BCA blue if omitted)
• Gitea: Creates missing labels with color (default: #ededed light gray if omitted)
• Azure DevOps: Tags don't support colors; color field is ignored

Backward Compatibility: Old string array format still works:

labels:
  add: ["ci::{{.State}}"]       # Go-templated string (no color)
  remove: ["ci::failed"]

Semantics:

• Remove runs before add, so a name in both lists converges to "present".
• Removing an absent label is success, not an error — the whole action is idempotent.
• Label names support Go templates over the event (ci::{{.State}} covers all states).
• Color conflicts: If a label already exists with a different color, the existing color is NOT modified (idempotent).
• Targets the PR if scm.pr-number is set, else the issue if scm.issue-number is set; otherwise the event is skipped.

check_run (GitHub)

Rich check UI with title/summary from the template. Use instead of commit_status when you want markdown output attached to the check.

deployment_status

Records the run as a deployment to an environment — it shows up in GitHub's Environments tab / GitLab's Environments page. The environment name comes from the scm.context annotation (default production).

• GitHub — creates the deployment and its status transitions.
• GitLab — creates a deployment via the Deployments API (running/success/failed/canceled; pending events are skipped).

Gate it with when so only your deploy pipelines trigger it:

- name: track-prod-deploys
  type: deployment_status
  enabled: true
  when: 'isPipelineRun() && event.PipelineName.startsWith("deploy-")'

Name filters

Independent of when, every action accepts allow/deny lists matched against the Tekton resource names:

filter:
  pipelines:
    allow: ["ci-pipeline", "release-pipeline"]
  tasks:
    deny: ["noisy-lint-task"]

Available lists: tasks, pipelines, custom_runs, event_listeners.