Advanced Repository Configuration
This guide is for regular users who need advanced Repository CR configurations, such as concurrency limits, source branch settings, and custom parameter expansion.
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
TOC
PrerequisitesCreating a Global Repository CRExample: Global Repository CRExample: Using Global SettingsStop Using the Global Repository CRSetting Concurrency LimitsConfigure Concurrency LimitExample Use CasesVerify Concurrency LimitChanging the Source Branch for Pipeline DefinitionConfigure PipelineRun definition sourceWhat the Setting DoesConfiguration comparisonCustom Parameter ExpansionDefine Custom ParametersUse Custom Parameters in PipelinesParameter PrecedenceExample: Environment-Specific ConfigurationCombining Advanced FeaturesBest Practices1. Concurrency Limits2. Source Branch Configuration3. Custom ParametersTroubleshootingConcurrency Limit Not WorkingParameters Not ExpandingNext StepsPrerequisites
- PAC component deployed and running
- A Repository CR created (see Guides)
- For the Repository samples that reference the Secret
my-repo-auth: that Secret, with the keysprovider.tokenandwebhook.secret, in the namespace of the Repository (project-pipelines, andproductionandstagingin Example: Environment-Specific Configuration), created in Create a Git Secret for PAC, Step 3; because it uses the default keys, these samples omitkey. The global Repository sample uses its own Secret, and themy-app-reposample inherits the Secret of the global Repository - The Repository samples use GitLab.com (
https://gitlab.com). For a self-hosted GitLab, setspec.urlto the project URL andgit_provider.urlto the GitLab base URL; withoutgit_provider.url, PAC can report the final status of a run tohttps://gitlab.comwith the Repository's token - Cluster administrator or namespace-level permissions
Creating a Global Repository CR
The global Repository CR feature is a Technology Preview feature that lets Repository CRs inherit shared configuration from one 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 TektonConfig CR). If you create a Repository CR named pipelines-as-code in this namespace, other Repository CRs inherit the fields of it that they leave unset, under the conditions listed under Behavior below.
Key Points:
- Name: Must be exactly
pipelines-as-code - Namespace: Must be in the PAC installation namespace (e.g.,
tekton-pipelines) - Inheritance: A Repository inherits only the fields it leaves unset;
git_providerfields and somesettingsfields are inherited only when the Repository has its owngit_providerorsettingsblock, andincomingis not inherited (see Behavior below) - Tech Preview: This is a Technology Preview feature
Example: Global Repository CR
Create a global Repository CR in the PAC namespace — the one in TektonConfig.spec.targetNamespace, which the example below assumes is the default tekton-pipelines. Replace it if your cluster uses a different one: PAC only reads the global Repository from its own namespace. In any other namespace, the PAC admission webhook rejects the example below because it has no spec.url: admission webhook "validation.pipelinesascode.tekton.dev" denied the request: URL must be set. Creating the global Repository and its Secret needs write access to Repositories and Secrets in the PAC namespace, usually a cluster administrator.
Create the Secret gitlab-webhook-config in the same namespace as the global Repository. A Repository that leaves git_provider.url unset inherits this url (see Behavior below); for a self-hosted GitLab, set it to the GitLab base URL.
Save the CR as global-repository.yaml and apply it:
Behavior:
git_provider: a Repository inherits the globalgit_providerfields (url,user,type,secret,webhook_secret) that it leaves unset, only when it has its owngit_providerblock whosetypeis empty or the same as the global one. A Repository without agit_providerblock, or with a differenttype, inherits none of these fieldssettings: a Repository inherits only these globalsettingsfields, when it leaves them unset and only when it has its ownsettingsblock:pipelinerun_provenance,policy,github_app_token_scope_repos,forgejo,aiandgitops_command_prefix. Provider settings such assettings.gitlabandsettings.github, which holdcomment_strategy, are not inherited; set them in each Repositoryconcurrency_limitandparams: a Repository takes the global value when it leaves the field unsetincoming: not inherited. PAC handles an incoming-webhook request only when the Repository named in the request has its ownincomingrules. Otherwise PAC drops the request: the caller gets HTTP200with an empty body, noPipelineRunis created, and the PAC controller log showserror processing incoming webhook: you need to have incoming webhooks rules in your repo spec, repo: <name>. Defineincomingin each Repository that receives incoming webhookssecretandwebhook_secret: set them the same way. Either set both in the Repository, referencing a Secret in the Repository's own namespace, or leave both unset in a Repository that inheritsgit_providerfields (see the first item), so that it inherits both; PAC then reads the token and the webhook secret from the namespace of the global Repository- A field that a Repository CR sets itself keeps its own value; the global value does not override it
- You still need to specify
spec.urland 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:
Stop Using the Global Repository CR
PAC reads the global Repository CR again for every webhook request, so deleting it takes effect at the next event: from then on, each Repository has only the fields that it sets itself. To stop using it, update the inheriting Repositories first, then delete it:
-
In each Repository that inherits from the global Repository CR, set the fields that it inherits. Under the conditions listed under Behavior above, these are the
git_providerfields (url,user,type,secret,webhook_secret),concurrency_limit,paramsand the listedsettingsfields that the Repository leaves unset;kubectl get repository <name> -n <namespace> -o yamlshows the fields that it sets itself. For the token and the webhook secret, create a Secret in the Repository's own namespace, as described in Create the Git Secret, and reference it from bothsecretandwebhook_secret: with both set in the Repository, PAC reads both from the Repository's namespace (see Behavior above). Aswebhook.secret, store the value that the Git provider webhook sends today; while the Repository's events pass, it equals the webhook secret that PAC reads for the Repository now (for a Repository that inherits bothsecretandwebhook_secret, such as themy-app-repoexample, the keywebhook.secretof the Secretgitlab-webhook-configin the PAC namespace). Reading a Secret in the PAC namespace needs read access to Secrets there, usually a cluster administrator. If the new Secret holds a different value, PAC drops the Git provider events of the Repository from the moment the Repository references it until the webhook sends the new value; on GitLab, the controller log then showscould not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secret. -
Delete the global Repository CR, and its Secret if nothing else uses it. This needs delete access to Repositories and Secrets in the PAC namespace, usually a cluster administrator. The commands in this section use
tekton-pipelines, the default ofTektonConfigspec.targetNamespace; replace it in the commands if your installation uses another namespace:
If you delete the global Repository CR first, a Repository that inherited secret or webhook_secret has no token or webhook secret at its next event, and PAC drops its events: no PipelineRun is created. For a Repository that inherited secret, the controller logs a line that ends with cannot get secret from repository: failed to find secret in git_provider section in repository spec: <namespace>/<name>; for one that inherited only webhook_secret, it logs one of the webhook secret errors in Troubleshooting in Configure GitLab Repository.
To see whether PAC reads a global Repository CR, check the PAC controller log; this needs read access to Pod logs in the PAC namespace, usually a cluster administrator. While a global Repository CR exists, PAC logs detected global repository settings named pipelines-as-code in namespace <pac-namespace> for every webhook request; after the deletion, new requests no longer log this line. The line does not name the Repository of the event. With -l, kubectl logs prints only the last 10 lines unless --tail is set, so the command reads every line of the last 10 minutes; increase --since if the event is older:
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:
Important:
- The minimum value is
1 - If neither the Repository nor a global Repository sets it, there is no limit on concurrent PipelineRuns. A Repository cannot remove a limit that it inherits from the global Repository:
0is rejected (spec.concurrency_limit in body should be greater than or equal to 1); it can only set its own value - 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:
Resource-intensive pipelines: Limit to ensure sufficient resources per run:
No limit (default, when no global Repository sets concurrency_limit): Allow unlimited concurrent runs:
Verify Concurrency Limit
Check the Repository CR:
Example output (abbreviated):
Monitor running PipelineRuns:
Example output:
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
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 branch whose name is the repository default branch as configured on the Git provider (for examplemain,master, ortrunk).
What the Setting Does
With default_branch, PAC reads the .tekton/ definitions from the branch whose name is the repository's default branch (for example main), whichever branch a pull request or merge request comes from. pipelinerun_provenance only selects the branch that PAC reads the definition from. It is not an access control: it does not restrict who can push to the default branch, and it does not require a review.
- Review comes from the Git provider: Protect the default branch and require merge request or pull request approval on the Git provider, so that every pipeline change is reviewed before it reaches the default branch.
To check that the setting took effect, open a test merge request or pull request that changes a value in a .tekton/ file, for example the text that a step prints, and read the PipelineRun that PAC creates for it (kubectl get pipelinerun <name> -n <namespace> -o yaml). With default_branch, the PipelineRun still has the value from the default branch; with source, it has the changed value. A Repository inherits pipelinerun_provenance from the global Repository only when it has its own settings block (see Behavior under Creating a Global Repository CR). Readers who can read Pod logs in the PAC namespace can also find Using PipelineRun definition from default_branch: <branch> in the PAC controller log.
Configuration comparison
Note: When you use default_branch, also protect the default branch and require reviews on the Git provider.
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:
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 }})
- Repository CR parameters from
-
Tekton parameters (
$(params.param)): Tekton resolves these during PipelineRun execution. These reference the PipelineRun's ownspec.params.
Reference Repository CR parameters in your PipelineRun definitions using PAC variable syntax:
Note: Replace the sample image alpine:latest with an image your cluster can pull, for example from an internal registry. The sample defines the pipeline inline with pipelineSpec; see the note in Define the Pipeline Inline with pipelineSpec for the cluster setting that this needs.
How it works:
- Before PipelineRun creation: PAC replaces all
{{ variable }}syntax with actual values from Repository CR params and built-in variables - PipelineRun creation: PAC creates the PipelineRun with all variables already replaced
- During execution: Tekton resolves
$(params.<name>)syntax by reading from the PipelineRun'sspec.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):
- PipelineRun params: Parameters explicitly defined in the PipelineRun
- Command and incoming-webhook params:
key=valuearguments of a GitOps command such as/test, which override only parameters already defined for theRepositoryor recognized by PAC (see Passing Parameters in Commands), and the params of an incoming-webhook request. PAC accepts an incoming-webhook param only when its name is listed in theparamsof the Repository'sincomingrule that matches the request. Otherwise PAC drops the whole request: the caller still gets HTTP200with an empty body, and noPipelineRunis created. An accepted request is answered with HTTP202and the body{"status":202,"message":"accepted"}. To check, list thePipelineRuns in the Repository's namespace (kubectl get pipelineruns -n <namespace>) after the request. The reason,error processing incoming webhook: param <name> is not allowed in incoming webhook CR, appears only in the PAC controller log; reading it needs read access to Pod logs in the PAC namespace, usually a cluster administrator - Repository params: Parameters defined in the Repository CR
- Dynamic variables: PAC dynamic variables (e.g.,
{{ revision }},{{ repo_url }})
Example: Environment-Specific Configuration
Configure different environments using Repository params. Each Repository references the Secret my-repo-auth in its own namespace, as listed in Prerequisites:
Production Repository:
Staging Repository:
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:
Best Practices
1. Concurrency Limits
- Set a limit per Repository: Base
concurrency_limiton the cluster resources and on the resources that eachPipelineRunof the Repository requests; the Example Use Cases use3for a high-traffic repository and2for resource-intensive pipelines. Do not set a limit for a Repository whosePipelineRuns usecancel-in-progress: while the Repository has a limit, set on it or inherited from a global Repository, a new run does not cancel the older runs, and PAC records the eventerror cancelling in progress pipelineRuns: cancel in progress is not supported with concurrency limiton theRepository(see Cancellation in Progress) - Watch for queued PipelineRuns: When the limit is reached, new
PipelineRuns wait with the state labelqueued; list them with thepipelinesascode.tekton.dev/statecolumn as shown in Concurrency Limit Not Working
2. Source Branch Configuration
- Choose one of the two sources:
pipelinerun_provenanceaccepts onlysource(the triggering branch, the default) ordefault_branch(the branch whose name is the repository default branch); it cannot name another branch - Test pipeline changes: With
default_branch, PAC reads the.tekton/definitions from the branch whose name is the repository's default branch (for examplemain), whichever branch a pull request or merge request comes from. Test changes to.tekton/before the merge in a Git repository whose Repository usessource, for example a non-production one; PAC accepts only one Repository per Git repository URL - 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: Do not pass credentials through Repository params. PAC writes a param value in clear text wherever
{{ name }}appears in the generatedPipelineRun, also when the value comes from a Secret throughsecret_ref(nameandkey) instead ofvalue:secret_refkeeps the value out of the Repository CR only. Mount credentials in the Task from a Kubernetes Secret instead, for example withenv.valueFrom.secretKeyRefor a Secret workspace. Usesecret_reffor values that must stay out of the Repository CR but may appear in thePipelineRun. PAC reads thesecret_refSecret from the Repository namespace; if it is not there, PAC records the Repository eventParamsError(error processing repository CR custom params: secrets "<secret-name>" not found), still creates thePipelineRun, and leaves{{ name }}unreplaced
Troubleshooting
Concurrency Limit Not Working
-
Verify the limit is set:
Example output for a Repository with a concurrency limit of 1, the limit used in the examples of steps 2 and 3:
An empty output means that the Repository does not set concurrency_limit itself. A limit that it takes from the global Repository applies without being written to the Repository, so also read spec.concurrency_limit of the global Repository pipelines-as-code in the PAC namespace; this needs read access to Repositories there, usually a cluster administrator.
-
Check for queued PipelineRuns: When the limit is reached, PAC still creates a
PipelineRunfor each new event, but keeps it pending (spec.status: PipelineRunPending) with the state labelqueued. When a runningPipelineRunof the same Repository finishes, the PAC watcher starts the next queued one, in creation order:
Example output:
The Repository status lists finished PipelineRuns only; a queued PipelineRun does not appear in it.
-
Verify PAC watcher logs: The queue is handled by the PAC watcher, not by the controller. Its log lines do not contain the word
concurrency, and PAC does not record them as events on theRepository. Reading the log needs read access to Pod logs in the PAC namespace, usually a cluster administrator. With-l,kubectl logsprints only the last 10 lines unless--tailis set, so the command reads every line of the last 10 minutes; increase--sinceif the runs started earlier. Replace<pac-namespace>with your PAC namespace (default:tekton-pipelines):
Example output (only the message shown):
The watcher also writes added pipelineRun (...) to running queue for a PipelineRun that has to wait; the next line no new PipelineRun acquired shows that it did not start.
Parameters Not Expanding
-
Verify parameters are defined:
An empty output means that the Repository does not set
paramsitself. If the global Repository setsparams, the Repository takes them (see Behavior under Creating a Global Repository CR), so also readspec.paramsof the global Repository. -
Check parameter syntax: Ensure you're using
{{ param }}syntax to reference Repository CR parameters, not$(params.param) -
Verify variable replacement: Check the created PipelineRun to see if PAC replaced the variables:
-
Review PipelineRun: Check if parameters are being overridden in the PipelineRun definition
Next Steps
- Guides - Basic repository setup walkthroughs
- Define PipelineRuns in Git - PipelineRun files and trigger annotations
- Incoming Webhooks - Direct HTTP triggers for external systems
- Common Issues - Troubleshooting guide