Custom Parameters

Custom Parameters #

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

By default, several variables are exposed according to the event. To view all the variables exposed by default, refer to the documentation on Authoring PipelineRuns.

With the custom parameter, you can specify some custom values to be replaced inside the template.

Utilizing the Tekton PipelineRun parameters feature may generally be the preferable approach, and custom params expansion should only be used in specific scenarios where Tekton params cannot be used.

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

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

The variable name {{ company }} will be replaced by My Beautiful Company anywhere inside your PipelineRun (including the remotely fetched task).

Alternatively, the value can be retrieved from a Kubernetes Secret. For instance, the following code will retrieve the value for the company parameter from a secret named my-secret and the key companyname:

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

Lastly, if no default value makes sense for a custom param, it can be defined without a value:

spec:
  params:
    - name: start_time

If the custom parameter is not defined with any value, it is only expanded if a value is supplied via a GitOps command.

If you have a value and a secret_ref defined, the value will be used.
If you don’t have a value or a secret_ref, and the parameter is not overridden by a GitOps command, the parameter will not be parsed, and it will be shown as {{ param }} in the PipelineRun.
If you don’t have a name in the params, the parameter will not be parsed.
If you have multiple params with the same name, the last one will be used.

CEL filtering on custom parameters #

You can define a param to only apply the custom parameters expansion when some conditions have been matched on a filter:

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

The pac prefix contains all the values as set by default in the templates variables. Refer to the Authoring PipelineRuns documentation for all the variables exposed by default.

The body of the payload is exposed inside the body prefix.

For example, if you are running a Pull Request on GitHub, pac will receive a payload that has this kind of JSON:

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

The filter can then do something like this:

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

The payload of the event contains much more information that can be used with the CEL filter. To see the specific payload content for your provider, refer to the API documentation

You can have multiple params with the same name and different filters; the first param that matches the filter will be picked up. This lets you have different output according to different events, and for example, combine a push and a pull request event.

GitHub Documentation for webhook events
GitLab Documentation for webhook events

Using custom parameters in CEL matching expressions #

In addition to template expansion ({{ param }}), custom parameters defined in the Repository CR are available as CEL variables in the on-cel-expression annotation. This allows you to control which PipelineRuns are triggered 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 use 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 from secrets are also available:

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.