Chapter 4. Using the Repository custom resource

You can use the tkn pac CLI or other alternative methods to create a Repository custom resource (CR) inside the target namespace. For example:

cat <<EOF|kubectl create -n my-pipeline-ci -f- 1

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: project-repository
spec:
  url: "https://github.com/<repository>/<project>"
EOF

Whenever there is an event coming from the URL such as https://github.com/<repository>/<project>, Pipelines as Code matches it and then starts checking out the content of the <repository>/<project> repository for pipeline run to match the content in the .tekton/ directory.

Optionally, you can create a global Repository custom resource (CR) in the namespace where OpenShift Pipelines is installed, normally openshift-pipelines. If you create this CR, the settings that you specify in it apply by default to all Repository CRs that you create.

You can use the concurrency_limit spec in the Repository custom resource definition (CRD) to define the maximum number of pipeline runs running simultaneously for a repository.

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repo
  namespace: target-namespace
spec:
# ...
  concurrency_limit: <number>
# ...

If there are multiple pipeline runs matching an event, the pipeline runs that match the event start in an alphabetical order.

For example, if you have three pipeline runs in the .tekton directory and you create a pull request with a concurrency_limit of 1 in the repository configuration, then all the pipeline runs are executed in an alphabetical order. At any given time, only one pipeline run is in the running state while the rest are queued.

By default, when processing a push event or a pull request event, Pipelines as Code fetches the pipeline definition from the branch that triggered the event. You can use the pipelinerun_provenance setting in the Repository custom resource definition (CRD) to fetch the definition from the default branch configured on the Git repository provider, such as main, master, or trunk.

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repo
  namespace: target-namespace
spec:
# ...
  settings:
    pipelinerun_provenance: "default_branch"
# ...

You can use Pipelines as Code to expand a custom parameter within your PipelineRun resource by using the params field. You can specify a value for the custom parameter inside the template of the Repository custom resource (CR). The specified value replaces the custom parameter in your pipeline run.

You can use custom parameters in the following scenarios:

The following example shows a custom parameter named company in the Repository CR:

...
spec:
  params:
    - name: company
      value: "ABC Company"
...

The value ABC Company replaces the parameter name company in your pipeline run and in the remotely fetched tasks.

You can also retrieve the value for a custom parameter from a Kubernetes secret, as shown in the following example:

...
spec:
  params:
    - name: company
      secretRef:
        name: my-secret
        key: companyname
...

Pipelines as Code parses and uses custom parameters in the following manner:

You can also define a custom parameter and use its expansion only when specified conditions were matched for a CEL filter. The following example shows a CEL filter applicable on a custom parameter named company when a pull request event is triggered:

...
spec:
  params:
    - name: company
      value: "ABC Company"
      filter:
        - name: event
          value: |
      pac.event_type == "pull_request"
...