Using the Repository custom resource | Pipelines as Code

Creating the Repository custom resource
Creating the global 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.

Creating the global Repository custom resource

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.

The global Repository CR is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Prerequisites

You have administrator access to the openshift-pipelines namespace.
You logged on to the OpenShift cluster using the oc command line utility.

Procedure

Create a Repository CR named pipeline-as-code in the openshift-pipelines namespace. Specify all the required default settings in this CR.
Example command to create the CR
```
$ cat <<EOF|oc create -n openshift-pipelines -f -

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: pipelines-as-code
spec:
  git_provider:
    secret:
      name: "gitlab-webhook-config"
      key: "provider.token"
    webhook_secret:
      name: "gitlab-webhook-config"
      key: "webhook.secret"
EOF
```
In this example, all Repository CRs that you create include the common secrets for accessing your GitLab repositories. You can set different repository URLs and other settings in the CRs.

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.