# Repository Spec
This page documents every field available under the Repository CR `spec`. Use this reference when configuring a Repository CR for your Git repository. The `spec` defines the desired state of a Repository, including its URL, Git provider configuration, and operational settings.

## Fields

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

### `url` — `string` — required


Specifies the repository URL. Must be a valid HTTP/HTTPS Git repository URL. Pipelines-as-Code uses this URL to clone the repository and fetch pipeline definitions from the `.tekton/` directory.

```yaml
spec:
  url: "https://github.com/owner/repository"
```




<a id="param-concurrency-limit"></a>

### `concurrency_limit` — `integer`


Sets the maximum number of concurrent PipelineRuns for this repository. This prevents resource exhaustion when many events trigger pipelines simultaneously. Minimum value: 1.

```yaml
spec:
  concurrency_limit: 5
```




<a id="param-git-provider"></a>

### `git_provider` — `GitProvider`


Configures how Pipelines-as-Code connects to your Git provider. Contains authentication credentials, API endpoints, and provider type information.

#### Show GitProvider Fields



<a id="param-git-provider-type"></a>

##### `git_provider.type` — `string`


Identifies the Git provider type. Pipelines-as-Code uses this to select the correct API and authentication flow. Supported values:

- `github` - GitHub.com or GitHub Enterprise
- `gitlab` - GitLab.com or self-hosted GitLab
- `bitbucket-datacenter` - Bitbucket Data Center (self-hosted)
- `bitbucket-cloud` - Bitbucket Cloud (bitbucket.org)
- `forgejo` - Forgejo instances
- `gitea` - Gitea instances (alias for forgejo, kept for backwards compatibility)

```yaml
git_provider:
  type: github
```




<a id="param-git-provider-url"></a>

##### `git_provider.url` — `string`


Specifies the Git provider API endpoint. Pipelines-as-Code sends API requests to this base URL (for example, `https://api.github.com` for GitHub or a custom GitLab instance URL).

```yaml
git_provider:
  url: "https://gitlab.example.com"
```




<a id="param-git-provider-user"></a>

##### `git_provider.user` — `string`


Sets the username for basic auth or token-based authentication. Pipelines-as-Code does not use this field for GitHub App authentication.
For Bitbucket Cloud, set this to the Atlassian account email that owns the
scoped API token.

```yaml
git_provider:
  user: "pac-bot"
```




<a id="param-git-provider-secret"></a>

##### `git_provider.secret` — `Secret`


References a Kubernetes Secret containing the credentials (token, password, or private key) that Pipelines-as-Code uses to authenticate with the Git provider API.

###### Show Secret Fields



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

###### `secret.name` — `string` — required


Name of the Kubernetes secret.



<a id="param-secret-key"></a>

###### `secret.key` — `string`


Key within the secret containing the value.






```yaml
git_provider:
  secret:
    name: github-token
    key: token
```




<a id="param-git-provider-webhook-secret"></a>

##### `git_provider.webhook_secret` — `Secret`


References a Kubernetes Secret containing the shared secret that Pipelines-as-Code uses to validate that incoming webhooks are legitimate and originate from the Git provider.

```yaml
git_provider:
  webhook_secret:
    name: webhook-secret
    key: secret
```







```yaml
spec:
  git_provider:
    type: github
    url: "https://github.com"
    user: "pac-bot"
    secret:
      name: github-token
      key: token
```




<a id="param-incoming"></a>

### `incoming` — `[]Incoming`


Configures incoming webhooks. Each entry specifies how Pipelines-as-Code handles external webhook requests that do not come from the primary Git provider.

#### Show Incoming Fields



<a id="param-incoming-type"></a>

##### `incoming[].type` — `string` — required


Specifies the incoming webhook type. Currently only `webhook-url` is supported, which allows external systems to trigger PipelineRuns via generic HTTP requests.



<a id="param-incoming-secret"></a>

##### `incoming[].secret` — `Secret` — required


References the Kubernetes Secret that Pipelines-as-Code uses to authenticate incoming webhook requests. Only requests with the matching secret value are accepted.

###### Show Secret Fields



<a id="param-incoming-secret-name"></a>

###### `secret.name` — `string` — required


Name of the Kubernetes secret.



<a id="param-incoming-secret-key"></a>

###### `secret.key` — `string`


Key within the secret containing the value.








<a id="param-incoming-params"></a>

##### `incoming[].params` — `[]string`


Lists parameter names to extract from the webhook payload. Pipelines-as-Code makes these parameters available to PipelineRuns triggered by this webhook.



<a id="param-incoming-targets"></a>

##### `incoming[].targets` — `[]string`


Lists the target branches for this webhook. Pipelines-as-Code triggers PipelineRuns only when the incoming request specifies one of these branches.






```yaml
spec:
  incoming:
    - type: webhook-url
      secret:
        name: webhook-secret
        key: token
      params:
        - branch
        - revision
      targets:
        - main
        - develop
```




<a id="param-params"></a>

### `params` — `[]Params`


Defines repository-level parameters that you can reference in PipelineRuns. Use these for default values or event-specific configuration.

#### Show Params Fields



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

##### `params[].name` — `string` — required


Sets the parameter name. Use this name to reference the parameter in PipelineRun definitions through the `{{ name }}` syntax.



<a id="param-params-value"></a>

##### `params[].value` — `string`


Sets the parameter value as a literal string. Pipelines-as-Code provides this value to the PipelineRun. This field is mutually exclusive with `secret_ref`.



<a id="param-params-secret-ref"></a>

##### `params[].secret_ref` — `Secret`


References a Kubernetes Secret containing the parameter value. Use this when the parameter contains sensitive information that you should not store directly in the Repository CR. This field is mutually exclusive with `value`.

###### Show Secret Fields



<a id="param-params-secret-name"></a>

###### `secret.name` — `string` — required


Name of the Kubernetes secret.



<a id="param-params-secret-key"></a>

###### `secret.key` — `string`


Key within the secret containing the value.








<a id="param-params-filter"></a>

##### `params[].filter` — `string`


Defines a CEL expression that controls when Pipelines-as-Code applies this parameter. Use this to conditionally apply parameters based on event type, branch name, or other attributes.






```yaml
spec:
  params:
    - name: deployment_env
      value: production
      filter: "event == 'push' && target_branch == 'main'"
    - name: api_key
      secret_ref:
        name: api-credentials
        key: key
```




<a id="param-settings"></a>

### `settings` — `Settings`


Configures repository-level settings, including authorization policies, provider-specific behavior, and provenance settings. See [Settings Reference](/nightly/docs/api/settings.md) for detailed documentation.

```yaml
spec:
  settings:
    pipelinerun_provenance: "source"
    policy:
      ok_to_test:
        - "trusted-user"
```




## Complete example

```yaml
spec:
  url: "https://github.com/organization/repository"
  concurrency_limit: 3
  git_provider:
    type: github
    url: "https://github.com"
    user: "pac-bot"
    secret:
      name: github-token
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret
  incoming:
    - type: webhook-url
      secret:
        name: incoming-webhook-secret
        key: token
      params:
        - version
        - environment
      targets:
        - main
  params:
    - name: cluster_name
      value: "production-cluster"
    - name: registry_token
      secret_ref:
        name: registry-credentials
        key: token
      filter: "event == 'push'"
  settings:
    pipelinerun_provenance: "source"
    github_app_token_scope_repos:
      - "organization/other-repo"
    gitops_command_prefix: "/my-prefix"
    policy:
      ok_to_test:
        - "maintainer-user"
        - "trusted-contributor"
      pull_request:
        - "external-contributor"
    github:
      comment_strategy: "update"
    gitlab:
      comment_strategy: "update"
      token_auto_rotation: true
    forgejo:
      user_agent: "my-custom-agent"
      comment_strategy: "update"
    ai:
      enabled: true
      provider: openai
      secret_ref:
        name: llm-api-token
        key: token
      roles:
        - name: failure-analysis
          prompt: "Analyze the CI/CD pipeline failure"
          model: "gpt-5.4-mini"
          on_cel: "pipelinerun_status == 'Failed'"
          output: pr-comment
          context_items:
            error_content: true
            container_logs:
              enabled: true
              max_lines: 100
```