CEL Expressions

This page covers CEL (Common Expression Language) expressions, which give you fine-grained control over which Git events trigger your PipelineRuns. Use CEL when simple annotation matching is not flexible enough – for example, when you want to exclude a specific branch, trigger only when certain file paths change, or filter on payload fields from your Git provider.

Basic usage

The following example matches a pull_request event targeting the main branch when the source branch is called wip:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request" && target_branch == "main" && source_branch == "wip"

Available CEL variables

The following fields are available inside CEL expressions:

Because CEL expressions can combine multiple conditions, they enable scenarios that simple annotations cannot handle. For example, to match a pull_request event but exclude the experimental branch:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request" && target_branch != "experimental"

Custom parameters in CEL expressions: limitations

Filtered parameters become undefined

If you use a custom parameter that has a filter in a CEL expression, and the filter condition is not met, the parameter is undefined. This causes a CEL evaluation error rather than evaluating to false.

For example, consider this Repository CR:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  url: "https://github.com/owner/repo"
  params:
    - name: docker_registry
      value: "registry.staging.example.com"
      filter: pac.event_type == "pull_request"

And this PipelineRun:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      docker_registry == "registry.staging.example.com"
spec:
  # ... pipeline spec

On a push event, the docker_registry parameter is not defined (because the filter only matches pull requests), so the CEL expression produces an error instead of false. Pipelines-as-Code does not evaluate the PipelineRun and reports an error.

To avoid undefined-parameter errors, reference custom parameters only when their filter conditions match, or use parameters without filters for CEL matching. You can test your CEL expressions against different event types with the tkn pac cel command to verify they work correctly across all scenarios.

Custom parameters cannot override built-in variables

Custom parameters you define in the Repository CR cannot override the built-in CEL variables that Pipelines-as-Code provides, such as:

• event (or event_type)
• target_branch
• source_branch
• trigger_target
• And other default variables documented in the table above

If you define a custom parameter with the same name as a built-in CEL variable, the built-in variable takes precedence. Always choose unique names for your custom parameters to avoid conflicts.

Matching by regex

You can match any CEL field using a regular expression. For example, to trigger a PipelineRun on pull_request events where the source_branch contains the substring feat/:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request" && source_branch.matches(".*feat/.*")

Matching by path change

Path-based matching lets you run a PipelineRun only when specific files change – for example, running documentation tests only when docs change, or skipping CI when only README files are updated.

To run a PipelineRun only when certain paths change, use the .pathChanged suffix function with a glob pattern. The following example matches every .md file in the docs directory:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request" && "docs/*.md".pathChanged()

The following example matches any changed file (added, modified, removed, or renamed) in the tmp directory:

    pipelinesascode.tekton.dev/on-cel-expression: |
      files.all.exists(x, x.matches('tmp/'))

This example matches any newly added file in the src or pkg directory:

    pipelinesascode.tekton.dev/on-cel-expression: |
      files.added.exists(x, x.matches('src/|pkg/'))

This example matches modified files named test.go:

    pipelinesascode.tekton.dev/on-cel-expression: |
      files.modified.exists(x, x.matches('test.go'))

Excluding non-code changes

When you want to run tests only when actual code changes occur – skipping documentation-only or config-only pull requests – you can negate a file pattern match:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request"
  && target_branch == "main"
  && !files.all.all(x, x.matches('^docs/') || x.matches('\\.md$') || x.matches('(\\.gitignore|OWNERS|PROJECT|LICENSE)$'))

This expression:

• Matches only pull_request events targeting the main branch.
• Skips the PipelineRun when every changed file matches one of these patterns:
  • Files in the docs/ directory (^docs/)
  • Markdown files (\\.md$)
  • Common repository metadata files (\\.gitignore, OWNERS, PROJECT, LICENSE)

The !files.all.all(x, x.matches(...)) pattern means “not every file matches these exclusion patterns.” In practice, Pipelines-as-Code triggers the PipelineRun only when at least one changed file falls outside the excluded patterns – that is, when there are meaningful code changes.

Matching by event title

The following example matches all pull requests whose title starts with [DOWNSTREAM]:

pipelinesascode.tekton.dev/on-cel-expression: |
  event == "pull_request" && event_title.startsWith("[DOWNSTREAM]")

For pull_request events, event_title contains the pull request title. For push events, it contains the commit title.

Matching by body payload

The full webhook payload body from the Git provider is available in the CEL variable body. You can use this variable to filter on any field your Git provider sends.

For example, this GitHub-specific expression:

pipelinesascode.tekton.dev/on-cel-expression: |
  body.pull_request.base.ref == "main" &&
    body.pull_request.user.login == "superuser" &&
    body.action == "synchronize"

matches only when the pull request targets the main branch, the pull request author is superuser, and the action is synchronize (meaning someone pushed new commits to the pull request).

# assuming you are on the branch you want to retest
# and the upstream remote are set
git commit --amend --no-edit && \
  git push --force-with-lease

Matching by request header

You can filter on webhook headers from the Git provider using the CEL variable headers. Header names are always lowercase.

For example, to verify the event is a pull_request on GitHub:

pipelinesascode.tekton.dev/on-cel-expression: |
  headers['x-github-event'] == "pull_request"