# Global Repository Settings> [!WARNING]
>
> **Global repository settings** 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.


This page explains how to configure a global Repository CR whose settings apply as defaults across all repositories on your cluster. Use this when you want to define shared configuration -- such as concurrency limits, Git provider credentials, or custom parameters -- in one place instead of repeating it in every namespace.

## How Inheritance Works

Pipelines-as-Code follows a two-tier inheritance model for Repository CR settings. A global Repository CR acts as a fallback: any setting you define there applies to every repository on the cluster unless a namespace-level Repository CR explicitly overrides it. When a namespace-level Repository CR does define a setting, that local value takes precedence over the global one.

This means you can set organization-wide defaults in the global Repository CR and let individual teams override only the settings they need.

```mermaid
flowchart LR
%% title: How the global Repository CR fills in a namespace Repository CR
  Ev@{ img: "/icons/webhook.svg", label: "Event", w: 48, h: 48, constraint: "on" }
  Local@{ img: "/icons/config.svg", label: "Repository CR", w: 48, h: 48, constraint: "on" }
  Global@{ img: "/icons/config.svg", label: "Global CR", w: 48, h: 48, constraint: "on" }
  Merge@{ img: "/icons/merge.svg", label: "Fill empty fields", w: 48, h: 48, constraint: "on" }
  Run@{ img: "/icons/pipeline.svg", label: "PipelineRun", w: 48, h: 48, constraint: "on" }
  Sec@{ img: "/icons/secret.svg", label: "Global secret", w: 48, h: 48, constraint: "on" }
  Git@{ img: "/icons/repository.svg", label: "Git provider", w: 48, h: 48, constraint: "on" }
  Stop@{ img: "/icons/refuse.svg", label: "Refused", w: 48, h: 48, constraint: "on" }
  Ev -->|matches| Local --> Merge
  Global -->|defaults| Merge
  Merge --> Run
  Merge same@-->|same type| Sec --> Git
  Merge other@-->|own url| Stop

%% play: Defaults filled in
%% skip Sec Git Stop
%% Ev -> Local : event | The event matches a Repository CR in user-namespace
%% Local, Global -> Merge | Only fields left empty in the Repository CR take the global value
%% Merge -> Run : limit 2 | The local concurrency_limit of 2 wins, and the global custom params fill the gap
%% play: Shared provider secret
%% skip Run Stop
%% Ev -> Local : gitlab
%% Local, Global -> Merge | Both set git_provider.type to gitlab, so the provider settings merge
%% Merge -> Sec @same : token | The secret is read from the namespace of the global Repository
%% Sec -> Git : token
%% play: Different provider type
%% skip Sec Git Stop
%% Ev -> Local : github
%% Local, Global -> Merge | The types differ, so git_provider is not merged at all
%% Merge -> Run | Other settings still merge, and the Repository CR needs its own provider secret
%% play: Own provider URL
%% skip Run Sec Git
%% Ev -> Local : event
%% Local, Global -> Merge | The Repository CR sets its own git_provider.url but no secret
%% Merge -> Stop @other | A credential from the controller namespace is never sent to another endpoint
```

## Creating the Global Repository CR

Create the global Repository CR in the namespace where the `pipelines-as-code` controller runs (typically `pipelines-as-code` or `openshift-pipelines`).

The global Repository CR does not need a real `spec.url`. You can leave the field blank or point it to a placeholder URL such as `https://pac.global.repo`.

By default, name the global Repository CR `pipelines-as-code`. If you need a different name, set the `PAC_CONTROLLER_GLOBAL_REPOSITORY` environment variable on both the controller and watcher Deployments.

## Available Global Settings

You can define the following settings in the global Repository CR:

- [Concurrency Limit](/docs/guides/repository-crd/concurrency.md).
- [PipelineRun Provenance](/docs/guides/repository-crd.md#pipelinerun-definition-provenance).
- [Repository Policy](/docs/advanced/policy-authorization.md).
- [Repository GitHub App Token Scope](/docs/guides/repository-crd/github-token-scoping.md#scoping-the-github-token-using-global-configuration).
- Git provider auth settings such as user, token, URL, etc.
  - The `type` must be defined in the namespace repository settings and must match the `type` of the global repository (see below for an example).
- [Custom Parameters](/docs/advanced/custom-parameters.md).
- [Incoming Webhooks Rules](/docs/advanced/incoming-webhooks.md).
- [Status Checks](/docs/guides/repository-crd/status-checks.md).

> [!NOTE]
>
> 
> Global settings are only applied when running via a Git provider event; they are not applied when for example using the `tkn pac` cli.
> 


## Example: How Inheritance Applies

Consider a namespace-level Repository CR in the `user-namespace` namespace:

```yaml
apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: repo
  namespace: user-namespace
spec:
  url: "https://my.git.com"
  concurrency_limit: 2
  git_provider:
    type: gitlab
```

And a global Repository CR in the controller namespace:

```yaml
apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: pipelines-as-code
  namespace: pipelines-as-code
spec:
  url: "https://paac.repo"
  concurrency_limit: 1
  params:
    - name: custom
      value: "value"
  git_provider:
    type: gitlab
    secret:
      name: "gitlab-token"
    webhook_secret:
      name: gitlab-webhook-secret
```

In this example, the `repo` Repository CR keeps its concurrency limit of 2 because the local setting overrides the global value of 1. The `custom` parameter with value `value` applies to every repository that does not define its own custom parameters.

Because the local Repository CR sets `git_provider.type` to `gitlab`, matching the global Repository CR, Pipelines-as-Code uses the Git provider settings (secret, webhook secret) from the global repository. It fetches the referenced secrets from the namespace where the global repository lives.

A namespace-level Repository that inherits `git_provider.secret` cannot set a different `git_provider.url`. Otherwise, someone who controls that Repository could redirect a credential owned by the controller namespace. To use another provider endpoint, configure `git_provider.secret` on the namespace-level Repository as well. This restriction applies to webhook-based providers; GitHub Apps use the controller's GitHub App credentials instead of inheriting this secret.

## Webhook-Based Provider Global Settings

The `spec.git_provider.type` field identifies which Git provider handles incoming webhooks. You can set it to any of the following values for webhook-based providers (everything except GitHub Apps):

- github (means a repository configured using [GitHub webhooks](/docs/providers/github-webhook.md))
- gitlab
- forgejo
- gitea (alias for forgejo, kept for backwards compatibility)
- bitbucket-cloud
- bitbucket-datacenter

The global Repository CR currently supports only one provider type per cluster. If you need to use a different provider for a specific repository, specify the full provider configuration in that repository's namespace-level Repository CR.


