# Settings
This page documents every field available under the Repository CR `settings` block. Use this reference when you need to configure authorization policies, provider-specific behavior, or provenance settings at the repository level.

## Settings fields

<a id="param-pipelinerun-provenance"></a>

### `pipelinerun_provenance` — `string`


Controls where Pipelines-as-Code fetches PipelineRun definitions from. Options:

- `source` - Fetch definitions from the event source branch/SHA (default)
- `default_branch` - Fetch definitions from the repository default branch

```yaml
settings:
  pipelinerun_provenance: "source"
```




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

### `github_app_token_scope_repos` — `[]string`


Lists additional repositories that Pipelines-as-Code includes in the GitHub App token scope. Use this when your PipelineRuns need to access other repositories on the same GitHub App installation, such as shared libraries or common task repositories.

```yaml
settings:
  github_app_token_scope_repos:
    - "organization/shared-library"
    - "organization/common-tasks"
```




<a id="param-gitops-command-prefix"></a>

### `gitops_command_prefix` — `string`


Sets a custom prefix for GitOps commands such as `/test`, `/retest`, and `/cancel`.
Use a plain word such as `pac`; Pipelines-as-Code adds the leading slash
automatically. For command behavior and examples, see the
[GitOps commands guide](/nightly/docs/guides/gitops-commands/advanced.md).

```yaml
settings:
  gitops_command_prefix: "pac"
```




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

### `policy` — `Policy`


Defines authorization policies for the repository. These policies control which users can trigger PipelineRuns under different conditions.

#### Show Policy Fields



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

##### `policy.ok_to_test` — `[]string`


Lists the team names whose members can trigger PipelineRuns on pull requests from external contributors by commenting `/ok-to-test`. These are typically maintainers or trusted contributors who can authorize CI for external contributions.

```yaml
settings:
  policy:
    ok_to_test:
      - "maintainer-username"
      - "trusted-contributor"
```




<a id="param-policy-pull-request"></a>

##### `policy.pull_request` — `[]string`


Lists the team names whose members can trigger PipelineRuns on their own pull requests, even if they would not normally have permission. Use this to grant specific external contributors the ability to run CI.

```yaml
settings:
  policy:
    pull_request:
      - "external-contributor"
      - "community-member"
```







```yaml
settings:
  policy:
    ok_to_test:
      - "team-lead"
      - "senior-dev"
    pull_request:
      - "trusted-external"
```




## Provider-specific settings

### GitHub settings

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

### `github` — `GithubSettings`


Configures GitHub-specific behavior for repositories hosted on GitHub.

#### Show GitHub Settings Fields



<a id="param-github-comment-strategy"></a>

##### `github.comment_strategy` — `string`


Controls how Pipelines-as-Code posts comments on GitHub pull requests. Options:

- `""` (empty) - Default behavior (create new comments)
- `disable_all` - Disables all comments on pull requests
- `update` - Updates a single comment per PipelineRun on every trigger

```yaml
settings:
  github:
    comment_strategy: "update"
```









### GitLab settings

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

### `gitlab` — `GitlabSettings`


Configures GitLab-specific behavior for repositories hosted on GitLab.

#### Show GitLab Settings Fields



<a id="param-gitlab-comment-strategy"></a>

##### `gitlab.comment_strategy` — `string`


Controls how Pipelines-as-Code posts comments on GitLab merge requests. Options:

- `""` (empty) - Default behavior (create new comments)
- `disable_all` - Disables all comments on merge requests
- `update` - Updates a single comment per PipelineRun on every trigger

```yaml
settings:
  gitlab:
    comment_strategy: "update"
```




<a id="param-gitlab-token-auto-rotation"></a>

##### `gitlab.token_auto_rotation` — `boolean`


Controls automatic rotation of expiring GitLab access tokens.

- Default: `false` (disabled)
- `true`: On each webhook event, Pipelines-as-Code checks token expiry and rotates when within 7 days

This can be set on the global Repository CR to enable rotation by default for repositories that do not set a local value.

```yaml
settings:
  gitlab:
    token_auto_rotation: true
```









### Forgejo/Gitea settings

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

### `forgejo` — `ForgejoSettings`


Configures Forgejo- and Gitea-specific behavior for repositories hosted on Forgejo or Gitea.

#### Show Forgejo Settings Fields



<a id="param-forgejo-user-agent"></a>

##### `forgejo.user_agent` — `string`


Sets the User-Agent header on API requests to the Gitea/Forgejo instance. This is useful when the instance is behind an AI scraping protection proxy (e.g., Anubis) that blocks requests without a recognized User-Agent. Defaults to `pipelines-as-code/<version>` when left empty.

```yaml
settings:
  forgejo:
    user_agent: "MyCustomBot/1.0"
```




<a id="param-forgejo-comment-strategy"></a>

##### `forgejo.comment_strategy` — `string`


Controls how Pipelines-as-Code posts comments on Forgejo/Gitea pull requests. Options:

- `""` (empty) - Default behavior (create new comments)
- `disable_all` - Disables all comments on pull requests
- `update` - Updates a single comment per PipelineRun on every trigger

```yaml
settings:
  forgejo:
    comment_strategy: "update"
```









## AI analysis settings

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

### `ai` — `AIAnalysisConfig`


Configures AI/LLM-powered analysis of pipeline failures and pull request content.

#### Show AIAnalysisConfig Fields



<a id="param-ai-enabled"></a>

##### `ai.enabled` — `boolean` — required


Enables or disables AI analysis for this repository.

```yaml
settings:
  ai:
    enabled: true
```




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

##### `ai.provider` — `string` — required


Sets the LLM provider for analysis. Supported values:

- `openai` - OpenAI (GPT models)
- `gemini` - Google Gemini

```yaml
settings:
  ai:
    provider: "openai"
```




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

##### `ai.api_url` — `string`


Overrides the default API endpoint for the LLM provider. Defaults:

- OpenAI: `https://api.openai.com/v1`
- Gemini: `https://generativelanguage.googleapis.com/v1beta`

Set this when you use self-hosted LLM instances, proxy services, or alternative endpoints.

```yaml
settings:
  ai:
    api_url: "https://custom-llm.example.com/v1"
```




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

##### `ai.secret_ref` — `Secret` — required


References the Kubernetes Secret containing the LLM provider API token.

```yaml
settings:
  ai:
    secret_ref:
      name: openai-token
      key: api-key
```




<a id="param-ai-timeout-seconds"></a>

##### `ai.timeout_seconds` — `integer`


Sets the maximum time in seconds to wait for LLM analysis (default: 30). Valid range: 1-300.

```yaml
settings:
  ai:
    timeout_seconds: 60
```




<a id="param-ai-max-tokens"></a>

##### `ai.max_tokens` — `integer`


Sets the maximum response length from the LLM (default: 1000). Valid range: 1-4000 tokens.

```yaml
settings:
  ai:
    max_tokens: 2000
```




<a id="param-ai-roles"></a>

##### `ai.roles` — `[]AnalysisRole` — required


Defines the analysis scenarios and their configurations. You must specify at least one role.

###### Show AnalysisRole Fields



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

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


Sets a unique identifier for this analysis role.



<a id="param-roles-prompt"></a>

###### `roles[].prompt` — `string` — required


Defines the base prompt template that Pipelines-as-Code sends to the LLM.



<a id="param-roles-model"></a>

###### `roles[].model` — `string`


Specifies the LLM model for this role. If omitted, Pipelines-as-Code uses provider-specific defaults:

- OpenAI: `gpt-5.4-mini`
- Gemini: `gemini-3.1-flash-lite-preview`



<a id="param-roles-on-cel"></a>

###### `roles[].on_cel` — `string`


Defines a CEL expression that determines when Pipelines-as-Code triggers this role.
Use the structured LLM CEL context, such as `body.event.*`,
`body.pipelineRun.*`, and `body.repository.*`.



<a id="param-roles-output"></a>

###### `roles[].output` — `string`


Specifies where Pipelines-as-Code sends the analysis results. Currently only `pr-comment` is supported (default).



<a id="param-roles-context-items"></a>

###### `roles[].context_items` — `ContextConfig`


Configures what context data Pipelines-as-Code includes in the analysis request.

###### Show ContextConfig Fields



<a id="param-context-items-commit-content"></a>

###### `context_items.commit_content` — `boolean`


Includes commit message and diff information in the analysis context.



<a id="param-context-items-pr-content"></a>

###### `context_items.pr_content` — `boolean`


Includes pull request title, description, and metadata in the analysis context.



<a id="param-context-items-error-content"></a>

###### `context_items.error_content` — `boolean`


Includes error messages and failure summaries in the analysis context.



<a id="param-context-items-container-logs"></a>

###### `context_items.container_logs` — `ContainerLogsConfig`


Configures whether Pipelines-as-Code includes container/task logs in the analysis context.

###### Show ContainerLogsConfig Fields



<a id="param-container-logs-enabled"></a>

###### `container_logs.enabled` — `boolean`


Enables or disables container log inclusion.



<a id="param-container-logs-max-lines"></a>

###### `container_logs.max_lines` — `integer`


Sets the maximum number of log lines to include (default: 50). Valid range: 1-1000 lines.
















```yaml
settings:
  ai:
    roles:
      - name: "failure-analysis"
        prompt: "Analyze the following CI/CD failure and suggest fixes"
        model: "gpt-4"
        on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"'
        context_items:
          commit_content: true
          error_content: true
          container_logs:
            enabled: true
            max_lines: 100
```









## Complete example

```yaml
apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: example-repo
  namespace: pipelines-as-code
spec:
  url: "https://github.com/organization/repository"
  settings:
    # Provenance configuration
    pipelinerun_provenance: "source"

    # GitHub App token scoping
    github_app_token_scope_repos:
      - "organization/shared-tasks"
      - "organization/common-library"

    # Authorization policies
    policy:
      ok_to_test:
        - "team-lead"
        - "senior-engineer"
        - "trusted-maintainer"
      pull_request:
        - "approved-contributor"

    # GitHub-specific settings
    github:
      comment_strategy: "update"

    # AI analysis configuration
    ai:
      enabled: true
      provider: "openai"
      api_url: "https://api.openai.com/v1"
      secret_ref:
        name: openai-credentials
        key: api-key
      timeout_seconds: 45
      max_tokens: 1500
      roles:
        - name: "pr-failure-analysis"
          prompt: |
            You are a CI/CD expert. Analyze the following pipeline failure and provide:
            1. Root cause analysis
            2. Specific fix recommendations
            3. Prevention strategies
          model: "gpt-4"
          on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"'
          output: "pr-comment"
          context_items:
            commit_content: true
            pr_content: true
            error_content: true
            container_logs:
              enabled: true
              max_lines: 100
        - name: "security-review"
          prompt: "Review this change for potential security issues"
          model: "gpt-4"
          on_cel: '"security-review" in body.event.pull_request_labels'
          context_items:
            commit_content: true
            pr_content: true
```

## Settings inheritance

You can define settings at the global level (in the ConfigMap) or the repository level (in the Repository CR). When both exist, repository-level settings override global settings.

## Related resources

- [Repository Spec](/nightly/docs/api/repository-spec.md) -- Complete Repository specification
- [ConfigMap Reference](/nightly/docs/api/configmap.md) -- Global configuration settings