Using the Repository custom resource | Pipelines as Code

Creating the Repository custom resource
Setting concurrency limits
Changing the source branch for the pipeline definition
Custom parameter expansion

The Repository custom resource (CR) has the following primary functions:

Inform Pipelines as Code about processing an event from a URL.
Inform Pipelines as Code about the namespace for the pipeline runs.
Reference an API secret, username, or an API URL necessary for Git provider platforms when using webhook methods.
Provide the last pipeline run status for a repository.

Creating 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

1	`my-pipeline-ci` is the target namespace.

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.

You must create the Repository CR in the same namespace where pipelines associated with the source code repository will be executed; it cannot target a different namespace.
If multiple Repository CRs match the same event, Pipelines as Code processes only the oldest one. If you need to match a specific namespace, add the pipelinesascode.tekton.dev/target-namespace: "<mynamespace>" annotation. Such explicit targeting prevents a malicious actor from executing a pipeline run in a namespace to which they do not have access.

Setting concurrency limits

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.

Changing the source branch for the pipeline definition

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 this setting as a security precaution. With the default behaviour, Pipelines as Code uses the pipeline definition in the submitted pull request. With the default-branch setting, the pipeline definition must be merged into the default branch before it is run. This requirement ensures maximum possible verification of any changes during merge review.

Custom parameter expansion

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:

To define a URL parameter, such as a registry URL that varies based on a push or a pull request.
To define a parameter, such as an account UUID that an administrator can manage without necessitating changes to the PipelineRun execution in the Git repository.

Use the custom parameter expansion feature only when you cannot use the Tekton PipelineRun parameters because Tekton parameters are defined in a Pipeline resource and customized alongside it inside a Git repository. However, custom parameters are defined and customized where the Repository CR is located. So, you cannot manage your CI/CD pipeline from a single point.

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:

If you have a value and a secretRef defined, Pipelines as Code uses the value.
If you do not have a name in the params section, Pipelines as Code does not parse the parameter.
If you have multiple params with the same name, Pipelines as Code uses the last parameter.

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"
...

When you have multiple parameters with the same name and different filters, Pipelines as Code uses the first parameter that matches the filter. So, Pipelines as Code allows you to expand parameters according to different event types. For example, you can combine a push and a pull request event.