# ConfigMap Reference
This page documents every field in the Pipelines-as-Code global ConfigMap. Use this reference when you need to change cluster-wide defaults for all repositories. Individual Repository CRs can override most of these settings.

## Location

Pipelines-as-Code installs the ConfigMap in the `pipelines-as-code` namespace by default:

```bash
kubectl get configmap pipelines-as-code -n pipelines-as-code
```

## Configuration Fields

### Application Settings

<a id="param-application-name"></a>

### `application-name` — `string` — default: `Pipelines as Code CI`


Sets the application name that Pipelines-as-Code displays in status updates and comments. If you use the GitHub App, also customize this label in the GitHub App settings.

```yaml
application-name: "Pipelines as Code CI"
```




### Secret Management

<a id="param-secret-auto-create"></a>

### `secret-auto-create` — `boolean` — default: `true`


Controls whether Pipelines-as-Code automatically creates a secret containing the Git provider token for use by the git-clone task.

```yaml
secret-auto-create: "true"
```




<a id="param-secret-github-app-token-scoped"></a>

### `secret-github-app-token-scoped` — `boolean` — default: `true`


Controls whether Pipelines-as-Code scopes generated tokens to only the repository that triggered the event. This setting is important when the GitHub App is installed on an organization with a mix of public and private repositories where some users should not access all repositories. Set to `false` if you trust every user in your organization to access all repositories, or if you are not installing your GitHub App at the organization level.

```yaml
secret-github-app-token-scoped: "true"
```




<a id="param-secret-github-app-scope-extra-repos"></a>

### `secret-github-app-scope-extra-repos` — `string`


Adds extra repositories to the token scope without disabling scoping entirely. List additional `owner/repo` pairs (on the same installation ID), separated by commas. Use this when your pipeline needs to access a shared library or dependency repository.

```yaml
secret-github-app-scope-extra-repos: "owner/private-repo1, org/repo2"
```




### Hub Configuration

<a id="param-hub-url"></a>

### `hub-url` — `string` — default: `<https://artifacthub.io>`


Specifies the default hub API URL that Pipelines-as-Code uses to fetch remote tasks.

```yaml
hub-url: "https://artifacthub.io"
```




<a id="param-catalog-n"></a>

### `catalog-{N}-*` — `object`


Configures additional hub catalogs. You can define multiple catalogs by incrementing the number (catalog-1-*, catalog-2-*, etc.).

#### Show Catalog Configuration Fields



<a id="param-catalog-n-id"></a>

##### `catalog-{N}-id` — `string`


Unique identifier for this catalog.



<a id="param-catalog-n-name"></a>

##### `catalog-{N}-name` — `string`


Name of the catalog.



<a id="param-catalog-n-url"></a>

##### `catalog-{N}-url` — `string`


URL of the catalog API endpoint.






```yaml
catalog-1-id: "custom"
catalog-1-name: "tekton"
catalog-1-url: "https://api.custom.hub"
```




<a id="param-remote-tasks"></a>

### `remote-tasks` — `boolean` — default: `true`


Controls whether Pipelines-as-Code fetches remote tasks from configured hubs.

```yaml
remote-tasks: "true"
```




### Dashboard Integration

Pipelines-as-Code generates links to PipelineRun details in status reports. The console used for those links is chosen in this order:

1. **Custom console**: if `custom-console-url` is set, it is used.
2. **Tekton Dashboard**: if `tekton-dashboard-url` is set (or the `PAC_TEKTON_DASHBOARD_URL` environment variable), it is used.
3. **OpenShift Console**: on OpenShift, the console URL is auto-detected from the `console` route in the `openshift-console` namespace. No configuration is needed.

When `custom-console-url` is set, `custom-console-url-pr-details`, `custom-console-url-namespace`, and `custom-console-url-pr-tasklog` should also be configured. Any missing field produces a broken placeholder link in status reports.

<a id="param-tekton-dashboard-url"></a>

### `tekton-dashboard-url` — `string`


Sets the Tekton dashboard URL. Pipelines-as-Code uses this base URL to generate links to PipelineRun details in status reports.

```yaml
tekton-dashboard-url: "https://tekton.example.com"
```




<a id="param-custom-console-name"></a>

### `custom-console-name` — `string`


Sets the display name for a custom console to use instead of the Tekton dashboard.

```yaml
custom-console-name: "Console Name"
```




<a id="param-custom-console-url"></a>

### `custom-console-url` — `string`


Sets the base URL of the custom console.

```yaml
custom-console-url: "https://url"
```




<a id="param-custom-console-url-pr-details"></a>

### `custom-console-url-pr-details` — `string`


Defines the template URL for PipelineRun details. Supports variables: `{{ namespace }}`, `{{ pr }}`.

```yaml
custom-console-url-pr-details: "https://url/ns/{{ namespace }}/{{ pr }}"
```




<a id="param-custom-console-url-pr-tasklog"></a>

### `custom-console-url-pr-tasklog` — `string`


Defines the template URL for task logs. Supports variables: `{{ namespace }}`, `{{ pr }}`, `{{ task }}`.

```yaml
custom-console-url-pr-tasklog: "https://url/ns/{{ namespace }}/{{ pr }}/logs/{{ task }}"
```




<a id="param-custom-console-url-namespace"></a>

### `custom-console-url-namespace` — `string`


Defines the template URL for namespace-level views in your custom console.
Supports the `{{ namespace }}` variable.

```yaml
custom-console-url-namespace: "https://url/ns/{{ namespace }}"
```




### Error Detection and Logging

<a id="param-error-log-snippet"></a>

### `error-log-snippet` — `boolean` — default: `true`


Controls whether Pipelines-as-Code shows a log snippet from the failed task when a Pipeline encounters an error. Disable this setting if your pipeline output may contain sensitive values.

```yaml
error-log-snippet: "true"
```




<a id="param-error-log-snippet-number-of-lines"></a>

### `error-log-snippet-number-of-lines` — `integer` — default: `3`


Sets the number of lines to display in error log snippets when `error-log-snippet` is `true`. Keep this value conservative because the GitHub Check interface has a 65,535 character limit.

```yaml
error-log-snippet-number-of-lines: "3"
```




<a id="param-error-detection-from-container-logs"></a>

### `error-detection-from-container-logs` — `boolean` — default: `true`


Controls whether Pipelines-as-Code inspects container logs to detect error messages and exposes them as annotations on pull requests. Only GitHub Apps are supported.

```yaml
error-detection-from-container-logs: "true"
```




<a id="param-error-detection-max-number-of-lines"></a>

### `error-detection-max-number-of-lines` — `integer` — default: `50`


Sets how many lines Pipelines-as-Code reads from the container when inspecting logs for error detection. Increasing this value may increase watcher memory usage. Use `-1` for unlimited lines.

```yaml
error-detection-max-number-of-lines: "50"
```




<a id="param-error-detection-simple-regexp"></a>

### `error-detection-simple-regexp` — `string`


Sets the default regular expression used for simple error detection. Must be a valid regular expression.

```yaml
error-detection-simple-regexp: |
  ^(?P<filename>[^:]*):(?P<line>[0-9]+):(?P<column>[0-9]+)?([ ]*)?(?P<error>.*)
```




### Concurrency Control

<a id="param-enable-cancel-in-progress-on-pull-requests"></a>

### `enable-cancel-in-progress-on-pull-requests` — `boolean` — default: `false`


Controls whether Pipelines-as-Code automatically cancels in-progress PipelineRuns for a pull request when that pull request receives a new push. This prevents redundant runs from consuming cluster resources.

```yaml
enable-cancel-in-progress-on-pull-requests: "false"
```




<a id="param-enable-cancel-in-progress-on-push"></a>

### `enable-cancel-in-progress-on-push` — `boolean` — default: `false`


Controls whether Pipelines-as-Code automatically cancels in-progress PipelineRuns triggered by a push event when a new push occurs on the same branch. This prevents overlapping runs for the same branch.

```yaml
enable-cancel-in-progress-on-push: "false"
```




### Bitbucket Cloud Settings

<a id="param-bitbucket-cloud-check-source-ip"></a>

### `bitbucket-cloud-check-source-ip` — `boolean` — default: `true`


Controls whether Pipelines-as-Code validates incoming webhook requests against Bitbucket Cloud's published IP ranges at <https://ip-ranges.atlassian.com/>. Because public Bitbucket does not support webhook secrets, IP verification is the primary security mechanism. This check applies only to public Bitbucket (when `provider.url` is not set in the Repository CR spec).

Disabling this setting creates a security risk. A malicious user could submit a pull request with a modified PipelineRun that exfiltrates secrets, then send a forged webhook payload to trigger it.

```yaml
bitbucket-cloud-check-source-ip: "true"
```




<a id="param-bitbucket-cloud-additional-source-ip"></a>

### `bitbucket-cloud-additional-source-ip` — `string`


Adds extra IPs (for example, `127.0.0.1`) or networks (for example, `127.0.0.0/16`) to the allowed list, separated by commas.

```yaml
bitbucket-cloud-additional-source-ip: "192.168.1.0/24, 10.0.0.1"
```




### Retention Policies

These settings control the global cleanup defaults. Individual PipelineRuns can
also set a per-run limit using the `pipelinesascode.tekton.dev/max-keep-runs`
annotation — see [PipelineRuns Cleanup](/nightly/docs/advanced/cleanup.md).

<a id="param-max-keep-run-upper-limit"></a>

### `max-keep-run-upper-limit` — `integer`


Sets the maximum value that a user can specify in the `max-keep-run` annotation on a PipelineRun. If a user sets a value higher than this limit, Pipelines-as-Code uses the upper limit during cleanup instead.

```yaml
max-keep-run-upper-limit: "100"
```




<a id="param-default-max-keep-runs"></a>

### `default-max-keep-runs` — `integer`


Sets the default cleanup retention count. Pipelines-as-Code applies this value to all PipelineRuns that do not have the `max-keep-runs` annotation.

```yaml
default-max-keep-runs: "10"
```




### Auto-Configuration

<a id="param-auto-configure-new-github-repo"></a>

### `auto-configure-new-github-repo` — `boolean` — default: `false`


Controls whether Pipelines-as-Code automatically creates a namespace and Repository CR for newly created repositories. Supported only with the GitHub App.

```yaml
auto-configure-new-github-repo: "false"
```




<a id="param-auto-configure-repo-namespace-template"></a>

### `auto-configure-repo-namespace-template` — `string`


Defines the template for generating namespace names when auto-configuring GitHub repositories. Supported fields: `{{repo_owner}}`, `{{repo_name}}`.

```yaml
auto-configure-repo-namespace-template: "{{repo_owner}}-{{repo_name}}"
```




<a id="param-auto-configure-repo-repository-template"></a>

### `auto-configure-repo-repository-template` — `string`


Defines the template for generating Repository CR names when auto-configuring GitHub repositories. Supported fields: `{{repo_owner}}`, `{{repo_name}}`.

```yaml
auto-configure-repo-repository-template: "{{repo_owner}}-{{repo_name}}-repo-cr"
```




### Security and Authorization

<a id="param-trusted-provider-hostnames"></a>

### `trusted-provider-hostnames` — `string`


Comma-separated list of Git provider hostnames that Pipelines-as-Code is allowed to send credentials to.

Pipelines-as-Code derives the provider API host it talks to from webhook data. This allowlist makes sure a crafted payload cannot redirect the controller, and its credentials, to a host an attacker controls.

The key has two states:

- **Controller managed** (the key is empty): the public hostnames `github.com`, `gitlab.com`, `bitbucket.org`, `gitea.com` and `codeberg.org` stay trusted, any other host is refused, and every request the provider itself authenticated adds its hostname to the `pipelinesascode.tekton.dev/auto-trusted-provider-hostnames` annotation. A default installation therefore needs no configuration, and a controller serving several instances learns all of them.
- **Administrator configured** (the key is non-empty): the list is authoritative for every hostname, public ones included, and the controller stops learning hosts. Listing only `ghe.example.com` is how an administrator says "this controller must never talk to a public SaaS instance".

The configuration key belongs only to administrators; the annotation belongs only to the controller. Keeping them separate makes the policy mode unambiguous even when both contain the same hostname.

A hostname that is not routable on the public internet (loopback, link-local, a private range, or an in-cluster `.svc` name) is never recorded automatically, since a payload must not be able to point the controller at the cloud metadata endpoint or an internal service. List it explicitly to trust it.

Paths that carry no provider signature, such as [incoming webhooks](/nightly/docs/advanced/incoming-webhooks.md), never record a hostname, so set this key explicitly on any self-hosted instance.

A value holding only whitespace or separators counts as unset, so use a real
hostname rather than a placeholder when you mean to configure the policy.

Removing a hostname from a non-empty list immediately narrows the policy.
Emptying the key returns to controller-managed mode, where previously learned
hosts become effective again. To return to a clean managed policy, empty the key
and delete the `pipelinesascode.tekton.dev/auto-trusted-provider-hostnames`
annotation.

Today the allowlist gates the GitHub provider; the other providers are being
moved onto it.

Each controller has its own ConfigMap and therefore its own allowlist.

```yaml
trusted-provider-hostnames: "ghe.example.com, gitlab.example.com"
```




<a id="param-remember-ok-to-test"></a>

### `remember-ok-to-test` — `boolean` — default: `false`


Controls whether Pipelines-as-Code remembers a previous `/ok-to-test` approval when new commits are pushed to a pull request. By default, users must issue `/ok-to-test` on each push. Set to `true` to persist the approval across push events.

```yaml
remember-ok-to-test: "false"
```




<a id="param-require-ok-to-test-sha"></a>

### `require-ok-to-test-sha` — `boolean` — default: `false`


Requires that a pull request's commit SHA be specified in an `/ok-to-test` comment. This prevents a race condition where a malicious user pushes a new commit after the `/ok-to-test` comment but before Pipelines-as-Code starts the CI run.

```yaml
require-ok-to-test-sha: "false"
```




<a id="param-skip-push-event-for-pr-commits"></a>

### `skip-push-event-for-pr-commits` — `boolean` — default: `true`


Prevents duplicate PipelineRuns when a commit appears in both a push event and a pull request. When a push event arrives from a commit that belongs to an open pull request, Pipelines-as-Code skips the push event.

```yaml
skip-push-event-for-pr-commits: "true"
```




### API Retry

> [!WARNING]
>
> **Provider API Retry for GitHub and GitLab** is a **Technology Preview** feature only.
> Technology Preview features are not currently supported and might not be functionally complete. We do not recommend using them in production. These features provide early access to upcoming Pipelines-as-Code features, enabling you to test functionality and provide feedback during the development process.


<a id="param-enable-api-retry"></a>

### `enable-api-retry` — `boolean` — default: `false`


Enables retrying GitHub and GitLab API requests when Pipelines-as-Code
encounters a temporary provider failure. This includes rate limits, temporary
server errors, and selected network failures.

Retries use backoff with jitter so multiple requests do not all retry at the
same time. When the provider supplies a retry or reset time, Pipelines-as-Code
uses that information as long as it does not exceed
`api-retry-max-wait-seconds`.

The setting is disabled by default. Enabling it affects API operations made
while processing an event, including temporary clients and GitHub App setup.

When disabled, the GitLab client keeps the retry behaviour built into the
upstream GitLab Go client, and the GitHub client performs no retries.

Pipelines-as-Code only repeats an operation when it can do so safely. It does
not repeat provider changes after an uncertain network or server failure when
doing so could create duplicate comments, statuses, or other mutations.

Independently of this setting, Pipelines-as-Code always retries a GitHub
check-run update that returns a 404 when the check-run id comes from the
annotation on a PipelineRun. Another reconcile may have created that check run
moments earlier and GitHub can still report it as missing, so the update is
retried a few times with a short backoff before the error is reported.

```yaml
enable-api-retry: "false"
```




<a id="param-api-retry-max-attempts"></a>

### `api-retry-max-attempts` — `integer` — default: `4`


Sets the maximum number of attempts when `enable-api-retry` is `true`. The
initial request counts as the first attempt. For example, a value of `4`
allows the initial request followed by up to three retries.

```yaml
api-retry-max-attempts: "4"
```




<a id="param-api-retry-max-wait-seconds"></a>

### `api-retry-max-wait-seconds` — `integer` — default: `120`


Sets the maximum time in seconds that Pipelines-as-Code waits between
attempts. If a provider asks the client to wait longer than this value,
Pipelines-as-Code stops retrying rather than holding the event for a long
cooling period.

```yaml
api-retry-max-wait-seconds: "120"
```




#### Failure reporting and limitations

If all attempts fail, Pipelines-as-Code reports the original provider error
through its normal logs, events, and provider status handling. Reporting a
failure status to GitHub or GitLab is best effort because a fully exhausted or
unavailable provider API might also reject the status update.

These settings are intended for short, temporary provider failures. They do
not provide persistent queueing for long rate-limit windows and do not control
how quickly a large backlog of PipelineRuns is admitted to the cluster.
Long-duration queueing and workload admission should be handled separately at
the pipeline or platform level.

## Complete Example

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: pipelines-as-code
  namespace: pipelines-as-code
  labels:
    app.kubernetes.io/part-of: pipelines-as-code
data:
  application-name: "My CI System"
  secret-auto-create: "true"
  secret-github-app-token-scoped: "true"
  secret-github-app-scope-extra-repos: "org/shared-repo"

  hub-url: "https://artifacthub.io"
  remote-tasks: "true"

  tekton-dashboard-url: "https://tekton.example.com"

  error-log-snippet: "true"
  error-log-snippet-number-of-lines: "5"
  error-detection-from-container-logs: "true"
  error-detection-max-number-of-lines: "100"

  enable-cancel-in-progress-on-pull-requests: "true"
  enable-cancel-in-progress-on-push: "false"

  max-keep-run-upper-limit: "50"
  default-max-keep-runs: "10"

  remember-ok-to-test: "true"
  require-ok-to-test-sha: "false"
  skip-push-event-for-pr-commits: "true"
```

## Updating configuration

You can edit the ConfigMap directly:

```bash
kubectl edit configmap pipelines-as-code -n pipelines-as-code
```

Or apply changes from a YAML file:

```bash
kubectl apply -f pipelines-as-code-config.yaml
```

Most changes take effect immediately. Some settings may require you to restart the Pipelines-as-Code controller.

## See Also

- [Settings](/nightly/docs/operations/settings.md) - Overview of global and per-repository configuration layers
- [Configuration](/nightly/docs/operations/configuration.md) - How to view and apply ConfigMap changes
- [Repository CR Settings Reference](/nightly/docs/api/settings.md) - Per-repository overrides
- [PipelineRuns Cleanup](/nightly/docs/advanced/cleanup.md) - Per-run retention using annotations
- [Global Repository Settings](/nightly/docs/operations/global-repository-settings.md) - Configure default settings for all repositories
- [Logging Configuration](/nightly/docs/operations/logging.md) - Configure log levels and debugging
- [Metrics](/nightly/docs/operations/metrics.md) - Monitor Pipelines-as-Code with Prometheus