Skip to main content

​
Overview

GitOps commands let you control Pipelines-as-Code directly from Git provider comments and commit messages. This creates a journal of all pipeline executions directly on your pull requests, next to your code. Available commands:
  • /test - Run all or specific pipelines
  • /retest - Retry failed pipelines
  • /cancel - Cancel running pipelines
  • /ok-to-test - Approve external contributor PRs
  • Custom commands via on-comment annotation

​
Pull Request Commands

GitOps commands work on pull request comments (all providers) and pushed commits (GitHub, GitLab).

​
/retest

Restart failed PipelineRuns or create new runs if none exist for the current commit. 
Thanks for the contribution! The failure seems to be infrastructure-related, not your code.

/retest
Behavior:
  • Creates new runs if previous runs failed
  • Creates new runs if no runs exist for the commit
  • Skips if successful runs already exist (avoids duplicates)
Force restart (even if successful): 
/retest my-pipeline-name
This always creates a new run.

​
/test

Run all matching PipelineRuns or a specific PipelineRun. 
/test
Runs all PipelineRuns that match the PR event. Target specific pipeline: 
/test my-pipeline-name
Runs only the my-pipeline-name PipelineRun. Difference from /retest:
  • /test runs regardless of previous status
  • /retest only runs if previous runs failed or don’t exist

​
/ok-to-test

Allow external contributors to run CI by approving their PR. 
Looks good! Thanks for the fix.

/ok-to-test
Only authorized users can use this command:
  • Repository owner
  • Repository collaborators
  • Organization members
  • Users in OWNERS file
  • Users in Repository CR policy.ok_to_test
See Running Pipelines - Authorization for details.

​
Require SHA (GitHub Only)

Cluster admins can enforce SHA validation for /ok-to-test:
pipelines-as-code ConfigMap
data:
  require-ok-to-test-sha: "true"
Users must include the commit SHA: 
/ok-to-test 1a2b3c4
PAC verifies:
  • Short SHAs (7-40 chars) match HEAD commit prefix
  • Full SHAs match exactly
If missing or invalid, the bot replies with instructions. Why? Prevents time-of-check/time-of-use attacks where an attacker pushes new code immediately after approval.

​
/cancel

Cancel running PipelineRuns. Cancel all: 
Infrastructure issues detected. Cancelling all runs.

/cancel
Cancel specific: 
/cancel my-pipeline-name
On GitHub Apps, the status changes to “cancelled”: Cancelled Pipeline
GitOps commands don’t work on closed pull requests or merge requests.

​
Pushed Commit Commands

Comment on commit to trigger commands:GitHub Commit CommentsHow to comment:
  1. Go to repository → Commits
  2. Click an individual commit
  3. Click a line number to add a comment

​
Branch Targeting

Commands on pushed commits target the latest commit (HEAD) of a branch. Default branch (no arguments): 
/test
/retest
/test my-pipeline
/retest my-pipeline
Runs on the default branch (main, master). Specific branch: 
/test branch:develop
/retest branch:feature-x
/test my-pipeline branch:staging
/cancel branch:hotfix

​
PipelineRun Configuration

For commit-based commands to work, the PipelineRun must be configured for push events on that branch:
.tekton/push-pipeline.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: push-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/on-target-branch: "[develop]"
spec:
  # ...
Then use: 
/test push-pipeline branch:develop
/ok-to-test does not work on pushed commits. It’s only for pull requests.

​
Commit in Multiple Branches

If a commit exists in multiple branches:
  • No branch specified: Uses the branch with the latest commit
  • Branch specified: Uses that specific branch

​
Git Tag Commands

Trigger PipelineRuns on tagged commits. Supported: GitHub (App and Webhook), GitLab 
/test tag:v1.0.0
/retest tag:v1.0.0
/test my-pipeline tag:v1.0.0
/cancel tag:v1.0.0
/cancel my-pipeline tag:v1.0.0
How to comment on a tag:
  1. Go to repository → Releases or Tags
  2. Click the tag (e.g., v1.0.0)
  3. Navigate to the tagged commit
  4. Add a comment on the commit
PipelineRun for tags:
.tekton/tag-release.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: tag-release
  annotations:
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/*]"
spec:
  pipelineSpec:
    tasks:
      - name: echo-tag
        taskSpec:
          steps:
            - name: echo
              image: registry.access.redhat.com/ubi10/ubi-micro
              script: |
                echo "Released tag: {{ git_tag }}"
Then trigger: 
/test tag:v1.0.0
The event type is push for tag events. Configure on-event: "[push]" and on-target-branch: "[refs/tags/*]".

​
Custom GitOps Commands

Create custom commands using the on-comment annotation.
​
pipelinesascode.tekton.dev/on-comment
string
Regex pattern to match comments
annotations:
  pipelinesascode.tekton.dev/on-comment: "^/deploy"
See Event Matching - Comment Triggers for details.

​
Example: Deploy Command

.tekton/deploy.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: deploy-staging
  annotations:
    pipelinesascode.tekton.dev/on-comment: "^/deploy-staging"
spec:
  pipelineSpec:
    tasks:
      - name: deploy
        taskSpec:
          steps:
            - name: deploy
              image: kubectl
              script: |
                kubectl apply -f manifests/staging/
Trigger with: 
/deploy-staging

​
Example: Merge PR Command

.tekton/merge-pr.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: merge-pr
  annotations:
    pipelinesascode.tekton.dev/on-comment: "^/merge-pr"
spec:
  params:
    - name: comment
      value: "{{ trigger_comment }}"
  pipelineSpec:
    params:
      - name: comment
    tasks:
      - name: merge
        taskSpec:
          params:
            - name: comment
          steps:
            - name: parse-comment
              image: alpine
              script: |
                # Parse comment for branch name
                echo "Comment: $(params.comment)"
                # Use GitHub API to merge PR
Trigger with: 
/merge-pr main

​
Accessing the Trigger Comment

When a GitOps command triggers a PipelineRun, the {{ trigger_comment }} variable is set. 
params:
  - name: trigger-comment
    value: "{{ trigger_comment }}"
Newlines are replaced with \n. Restore them in shell scripts: 
steps:
  - name: process-comment
    image: alpine
    script: |
      echo -e "{{ trigger_comment }}" > /tmp/comment
      grep "/deploy" /tmp/comment

​
Passing Arguments to Commands

Override dynamic variables or custom parameters: 
/test my-pipeline env=staging region=us-west-2
Requirements:
  • Parameter must be defined as a custom parameter in Repository CR or be a standard dynamic variable
  • Cannot pass arbitrary undefined parameters
Supported formats: 
key=value
key="value with spaces"
key="value with \"quotes\""
key="multiline
value"
Example Repository CR: 
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
spec:
  url: "https://github.com/owner/repo"
  params:
    - name: env
      value: "dev"  # Default
    - name: region
      value: "us-east-1"  # Default
Override via comment: 
/test deploy-pipeline env=production region=eu-west-1

​
Event Type Annotation

The pipeline.tekton.dev/event-type annotation indicates which GitOps command triggered the run:
Annotation ValueDescription
test-all-comment/test (all pipelines)
test-comment/test <pipeline-name>
retest-all-comment/retest (all failed)
retest-comment/retest <pipeline-name>
ok-to-test-comment/ok-to-test
cancel-all-comment/cancel (all runs)
cancel-comment/cancel <pipeline-name>
on-commentCustom comment trigger
Dynamic Variable {{ event_type }}: For backward compatibility, {{ event_type }} returns pull_request for:
  • test-all-comment
  • test-comment
  • retest-all-comment
  • retest-comment
  • ok-to-test-comment
This behavior is deprecated and will change in future releases to return the specific event type.

​
Non-Matching PipelineRun Trigger

GitOps commands can trigger PipelineRuns regardless of annotations: 
/test my-pipeline
This runs my-pipeline even if its annotations don’t match the current event. Use case: Pipelines triggered only by comments, not automatic events.
.tekton/manual-deploy.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: manual-deploy
  # No on-event or on-target-branch annotations
spec:
  # Only runs via /test manual-deploy

​
Neutral Status on No Match

If /ok-to-test is used but no PipelineRuns match:
  • GitHub: Neutral commit status posted (“No pipelines matched”)
  • Allows other workflows (e.g., auto-merge) to proceed
Neutral status is only supported on GitHub.

​
Examples

​
Basic PR Workflow

# External contributor opens PR
# Bot posts: "User lacks permissions. Repository owners can comment '/ok-to-test'"

# Repository owner reviews code
/ok-to-test

# Later, infrastructure fails
/retest

# Run specific pipeline
/test security-scan

​
Pushed Commit Workflow

# Developer pushes to feature branch
# Comment on commit:
/test branch:feature/new-feature

# Cancel if needed
/cancel branch:feature/new-feature

​
Tag Release Workflow

# Create tag
git tag v1.0.0
git push origin v1.0.0

# Comment on tag commit:
/test tag:v1.0.0

# Later, retry release
/retest release-pipeline tag:v1.0.0

​
Custom Deploy Workflow

# PR approved, ready to deploy
/deploy-staging

# After validation
/deploy-production region=us-west-2

# Rollback if needed
/deploy-staging version=v1.0.0

​
Best Practices

1
Document custom commands
2
Add a comment in your PipelineRun:
3
metadata:
  name: deploy-staging
  annotations:
    # Trigger with: /deploy-staging
    pipelinesascode.tekton.dev/on-comment: "^/deploy-staging"
4
Or in your repository README:
5
## GitOps Commands

- `/test` - Run all pipelines
- `/retest` - Retry failed pipelines
- `/deploy-staging` - Deploy to staging environment
- `/deploy-production` - Deploy to production
6
Use /retest for transient failures
7
Save resources by only retrying failures:
8
/retest
9
Instead of always using /test.
10
Require SHA for /ok-to-test
11
In production environments, enable SHA validation:
12
data:
  require-ok-to-test-sha: "true"
13
Use branch targeting on monorepos
14
Test specific branches without affecting others:
15
/test service-a branch:feature/new-api
16
Combine with parameters
17
Make commands flexible:
18
/test deploy env=staging region=us-east-1 replicas=3

​
Troubleshooting

​
Command not triggering

1
Verify comment format
2
Commands must start the comment (after whitespace):
3
✅ /test
✅ /test my-pipeline
❌ Let's run /test  # Won't work
4
Check authorization
5
Ensure user is authorized (see Running Pipelines - Authorization).
6
Verify PipelineRun exists
7
ls .tekton/
8
Check the PipelineRun file exists and has correct name.
9
Check PAC controller logs
10
kubectl logs -n pipelines-as-code -l app.kubernetes.io/name=controller

​
/retest not creating new runs

Expected behavior: /retest only runs if:
  • Previous runs failed, OR
  • No runs exist yet
If successful runs exist, use: 
/test my-pipeline

​
Custom command not matching

Verify regex pattern: 
annotations:
  # Matches: /deploy-staging
  pipelinesascode.tekton.dev/on-comment: "^/deploy-staging"
  
  # Matches: /deploy staging or /deploy production
  pipelinesascode.tekton.dev/on-comment: "^/deploy (staging|production)"

​
Next Steps

Event Matching

Configure comment-based triggers with on-comment annotation

Running Pipelines

Understand authorization and execution

Creating Pipelines

Use trigger_comment variable in PipelineRuns

Repository CRD

Configure authorization policies for ok-to-test

Build docs developers (and LLMs) love

Get started for freeTalk to us