Custom Parameters

This page explains how to define and use custom parameters in your PipelineRuns. Use custom parameters when you need to inject repository-level values, such as environment names or secrets, into your pipeline templates.

Overview

Using the {{ param }} syntax, Pipelines-as-Code lets you expand a variable or the payload body inside a template within your PipelineRun.

Pipelines-as-Code exposes several variables by default, depending on the event type. For the full list, refer to the Authoring PipelineRuns documentation.

Custom parameters let you define additional values that Pipelines-as-Code replaces inside the template at runtime.

For example, here is a custom variable in the Repository CR spec:

spec:
  params:
    - name: company
      value: "My Beautiful Company"

Pipelines-as-Code replaces the variable name {{ company }} with My Beautiful Company anywhere inside your PipelineRun, including remotely fetched tasks.

You can also retrieve the value from a Kubernetes Secret. For example, the following configuration retrieves the company parameter from a secret named my-secret and the key companyname:

spec:
  params:
    - name: company
      secret_ref:
        name: my-secret
        key: companyname

If no default value makes sense for a custom parameter, you can define it without a value:

spec:
  params:
    - name: start_time

If you define a custom parameter without a value, Pipelines-as-Code expands it only when a value is supplied via a GitOps command.

CEL filtering on custom parameters

You can restrict when Pipelines-as-Code expands a custom parameter by adding a filter field. The filter uses a CEL expression, and Pipelines-as-Code applies the parameter only when the expression evaluates to true:

spec:
  params:
    - name: company
      value: "My Beautiful Company"
      filter: pac.event_type == "pull_request"

The pac prefix exposes all default template variables. Refer to the Authoring PipelineRuns documentation for the complete list.

The body prefix exposes the raw webhook payload.

For example, when you open a pull request on GitHub, the incoming payload contains JSON like this:

{
  "action": "opened",
  "number": 79,
  // .... more data
}

You can then match against those payload fields in your filter:

spec:
  params:
    - name: company
      value: "My Beautiful Company"
      filter: body.action == "opened" && pac.event_type == "pull_request"

The event payload contains additional fields that you can reference in your CEL filter. To see the full payload structure for your Git provider, refer to the provider’s API documentation.

You can define multiple params with the same name but different filters. Pipelines-as-Code picks the first parameter whose filter matches. This lets you produce different values depending on the event type – for example, using one value for push events and another for pull request events.

Using custom parameters in CEL matching expressions

Beyond template expansion ({{ param }}), you can also use custom parameters as CEL variables in the on-cel-expression annotation. This gives you control over which PipelineRuns Pipelines-as-Code triggers, based on repository-specific configuration.

For example, with this Repository CR configuration:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  url: "https://github.com/owner/repo"
  params:
    - name: enable_ci
      value: "true"
    - name: environment
      value: "staging"

You can reference these parameters directly in your PipelineRun’s CEL expression:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "push" && enable_ci == "true" && environment == "staging"
spec:
  # ... pipeline spec

This approach is particularly useful for:

• Conditional CI: Enable or disable CI for specific repositories without changing PipelineRun files
• Environment-specific matching: Run different pipelines based on environment configuration
• Feature flags: Control which pipelines run using repository-level feature flags

Custom parameters sourced from secrets are also available in CEL expressions:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  url: "https://github.com/owner/repo"
  params:
    - name: api_key
      secret_ref:
        name: my-secret
        key: key

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline-with-secret
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "push" && api_key != ""
spec:
  # ... pipeline spec

For more information on CEL expressions and event matching, see the Advanced event matching using CEL documentation.