#Advanced Repository Configuration

This guide explains advanced configuration options for Repository Custom Resources, including:

• Global Repository CR for automatic configuration inheritance (Tech Preview)
• Concurrency limits
• Source branch configuration
• Custom parameter expansion

#Prerequisites

• PAC component deployed and running
• A Repository CR created (see Configure Repository)
• Cluster administrator or namespace-level permissions

#Creating a Global Repository CR

Alternatively, you can create a global Repository CR in the namespace where PAC is installed (typically tekton-pipelines or configured via targetNamespace in the OpenShiftPipelinesAsCode CR). If you create a Repository CR named pipelines-as-code in this namespace, the settings you specify in it will be automatically applied to all Repository CRs you create.

Key Points:

• Name: Must be exactly pipelines-as-code
• Namespace: Must be in the PAC installation namespace (e.g., tekton-pipelines)
• Auto-apply: Settings automatically apply to all Repository CRs
• Tech Preview: This is a Technology Preview feature

#Example: Global Repository CR

Create a global Repository CR in the PAC namespace:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines  # PAC installation namespace
spec:
  git_provider:
    secret:
      name: gitlab-webhook-config
      key: provider.token
    webhook_secret:
      name: gitlab-webhook-config
      key: webhook.secret

Apply the CR:

kubectl apply -f global-repository.yaml

Behavior:

• All Repository CRs you create will inherit these git_provider settings
• Individual Repository CRs can override these settings if needed
• You still need to specify url and other repository-specific settings in each Repository CR

#Example: Using Global Settings

With the global CR above, you can create individual Repository CRs with minimal configuration:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-app-repo
  namespace: my-project
spec:
  url: "https://gitlab.com/user/my-app"
  # git_provider settings are inherited from the global CR

#Setting Concurrency Limits

Concurrency limits help prevent resource exhaustion when many events trigger pipelines simultaneously. You can set the maximum number of concurrent PipelineRuns that can run for a repository.

#Configure Concurrency Limit

Edit your Repository CR to add the concurrency_limit field:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

Important:

• The minimum value is 1
• If not specified, there is no limit on concurrent PipelineRuns
• When the limit is reached, new events will queue until a PipelineRun completes

#Example Use Cases

High-traffic repository: Limit concurrent runs to prevent cluster overload:

spec:
  concurrency_limit: 3

Resource-intensive pipelines: Limit to ensure sufficient resources per run:

spec:
  concurrency_limit: 2

No limit (default): Allow unlimited concurrent runs:

spec:
  # concurrency_limit not specified

#Verify Concurrency Limit

Check the Repository CR:

kubectl get repository my-repo -n project-pipelines -o yaml

Example output (abbreviated):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  concurrency_limit: 2

Monitor running PipelineRuns:

kubectl get pipelineruns -n project-pipelines | grep Running

Example output:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Running
test-pipeline-yyyyy     1 minute ago   45s        Running

#Changing the Source Branch for Pipeline Definition

By default, Pipelines-as-Code fetches the PipelineRun definition from the branch where the event has been triggered (for example, the branch of the push or pull request).

You can change this behavior by using the spec.settings.pipelinerun_provenance field in the Repository custom resource. This setting controls from which branch the PipelineRun definition is fetched.

#Configure PipelineRun definition source

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
  settings:
    pipelinerun_provenance: "default_branch"

Supported values for pipelinerun_provenance:

• source: The default behavior. The PipelineRun definition is fetched from the branch where the event has been triggered.
• default_branch: The PipelineRun definition is fetched from the repository default branch as configured on the Git provider (for example main, master, or trunk).

#Security Benefits

Letting the user specify the provenance of the PipelineRun definition to the default branch is another layer of security. It ensures that only the user who has the right to merge commits to the default branch can change the PipelineRun definition and gain access to the infrastructure.

• Prevents malicious pipeline changes: Pipeline definitions must be merged to the default branch before they can be executed.
• Enforces review process: All pipeline changes go through the standard merge/review process.
• Consistent pipeline behavior: All runs use the same pipeline definitions from the default branch.

#Configuration comparison

Note: According to the Red Hat OpenShift Pipelines documentation, the default_branch setting is recommended as a security measure to ensure maximum validation of pipeline changes during the merge review process.

#Custom Parameter Expansion

You can define custom parameters in the Repository CR that will be expanded in all PipelineRuns created for that repository. This is useful for setting common values across all pipelines.

#Define Custom Parameters

Add parameters to the Repository CR spec.params field:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  - name: namespace
    value: "production"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token

#Use Custom Parameters in Pipelines

Important: Repository CR parameters use the PAC variable syntax {{ param }}, not Tekton's $(params.param) syntax.

• PAC variables ({{ variable }}): PAC replaces these before creating the PipelineRun. This includes:

  • Repository CR parameters from spec.params (e.g., {{ environment }}, {{ cluster-name }})
  • PAC built-in variables (e.g., {{ revision }}, {{ repo_url }}, {{ source_branch }})

• Tekton parameters ($(params.param)): Tekton resolves these during PipelineRun execution. These reference the PipelineRun's own spec.params.

Reference Repository CR parameters in your PipelineRun definitions using PAC variable syntax:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: deploy-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  params:
  - name: environment
    value: "{{ environment }}"  # PAC variable - replaced with Repository CR param value
  - name: cluster-name
    value: "{{ cluster-name }}"  # PAC variable - replaced with Repository CR param value
  - name: namespace
    value: "{{ namespace }}"  # PAC variable - replaced with Repository CR param value
  - name: revision
    value: "{{ revision }}"  # PAC built-in variable - replaced with commit SHA
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            echo "Deploying to $(params.environment)"  # Tekton parameter syntax in script
            echo "Cluster: $(params.cluster-name)"
            echo "Namespace: $(params.namespace)"
            echo "Commit: $(params.revision)"

How it works:

1. Before PipelineRun creation: PAC replaces all {{ variable }} syntax with actual values from Repository CR params and built-in variables
2. PipelineRun creation: PAC creates the PipelineRun with all variables already replaced
3. During execution: Tekton resolves $(params.xxx) syntax by reading from the PipelineRun's spec.params

Example transformation:

• In your Git repo: value: "{{ environment }}"
• PAC replaces it: value: "production" (from Repository CR param)
• PipelineRun created with: - name: environment / value: "production"
• Task scripts use: $(params.environment) → Tekton resolves to "production"

#Parameter Precedence

Parameters are expanded in the following order (highest to lowest precedence):

1. PipelineRun params: Parameters explicitly defined in the PipelineRun
2. Repository params: Parameters defined in the Repository CR
3. Dynamic variables: PAC dynamic variables (e.g., {{ revision }}, {{ repo_url }})

#Example: Environment-Specific Configuration

Configure different environments using Repository params:

Production Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: prod-repo
  namespace: production
spec:
  url: "https://gitlab.com/user/prod-repo"
  params:
  - name: environment
    value: "production"
  - name: api-url
    value: "https://api.production.example.com"
  - name: registry
    value: "registry.production.example.com"

Staging Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: staging-repo
  namespace: staging
spec:
  url: "https://gitlab.com/user/staging-repo"
  params:
  - name: environment
    value: "staging"
  - name: api-url
    value: "https://api.staging.example.com"
  - name: registry
    value: "registry.staging.example.com"

Both repositories can use the same pipeline definition, with parameters automatically filled from the Repository CR.

#Combining Advanced Features

You can combine all advanced features in a single Repository CR:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: advanced-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

#Best Practices

#1. Concurrency Limits

• Set appropriate limits: Consider your cluster resources and pipeline resource requirements
• Monitor usage: Watch for queued events when limits are too low
• Adjust dynamically: Increase limits for high-traffic periods, decrease for resource conservation

#2. Source Branch Configuration

• Use stable branches: Fetch pipeline definitions from stable branches (e.g., main)
• Test pipeline changes: Test pipeline changes in feature branches before merging to the source branch
• Document changes: Clearly document which branch contains pipeline definitions

#3. Custom Parameters

• Use meaningful names: Choose clear, descriptive parameter names
• Keep values simple: Use simple string values for parameters
• Document parameters: Document what each parameter does and when it's used
• Avoid secrets: Don't store secrets in Repository params; use Kubernetes Secrets instead

#Troubleshooting

#Concurrency Limit Not Working

1. Verify the limit is set:

   kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.concurrency_limit}'

Example output:

2 # This is the concurrency limit

2. Check for queued events: Look for events that are waiting for PipelineRuns to complete

3. Verify PAC controller logs:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep concurrency  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

Example output:

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Concurrency limit reached","repository":"my-repo","limit":2,"running":2}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun queued","repository":"my-repo","reason":"concurrency_limit"}

#Parameters Not Expanding

1. Verify parameters are defined:

   kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.params}'

2. Check parameter syntax: Ensure you're using {{ param }} syntax to reference Repository CR parameters, not $(params.param)

3. Verify variable replacement: Check the created PipelineRun to see if PAC replaced the variables:

   kubectl get pipelinerun <run-name> -n <namespace> -o yaml | grep -A 5 "params:"

4. Review PipelineRun: Check if parameters are being overridden in the PipelineRun definition

#Next Steps

• Configure Repository - Basic repository setup
• Maintain Pipeline Code - Pipeline definition guide
• Manage PipelineRuns - PipelineRun management
• Common Issues - Troubleshooting guide