Settings Reference

The settings field in the Repository spec contains configuration settings for the repository, including authorization policies, provider-specific configuration, and provenance settings.

Settings Fields

pipelinerun_provenance

string

Configures how PipelineRun definitions are fetched.Options:

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

settings:
  pipelinerun_provenance: "source"

github_app_token_scope_repos

[]string

Lists repositories that can access the GitHub App token when using the GitHub App authentication method. This allows specific repositories to use tokens generated for the GitHub App installation, useful for cross-repository access.

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

policy

Policy

Defines authorization policies for the repository, controlling who can trigger PipelineRuns under different conditions.

Show Policy Fields

policy.ok_to_test

[]string

List of usernames that are allowed to trigger pipeline runs on pull requests from external contributors by commenting /ok-to-test on the PR. These users are typically repository maintainers or trusted contributors who can vouch for external contributions.

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

policy.pull_request

[]string

List of usernames that are explicitly allowed to execute pipelines on their pull requests, even if they wouldn’t normally have permission. This is useful for allowing specific external contributors to trigger pipeline runs.

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

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

Provider-Specific Settings

GitHub Settings

github

GithubSettings

GitHub-specific settings for repositories hosted on GitHub.

Show GitHub Settings Fields

github.comment_strategy

string

Defines how GitHub comments are handled for pipeline results.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

settings:
  github:
    comment_strategy: "update"

GitLab Settings

gitlab

GitlabSettings

GitLab-specific settings for repositories hosted on GitLab.

Show GitLab Settings Fields

gitlab.comment_strategy

string

Defines how GitLab comments are handled for pipeline results.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

settings:
  gitlab:
    comment_strategy: "update"

Forgejo/Gitea Settings

forgejo

ForgejoSettings

Forgejo/Gitea-specific settings for repositories hosted on Forgejo or Gitea.

Show Forgejo Settings Fields

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.

settings:
  forgejo:
    user_agent: "MyCustomBot/1.0"

forgejo.comment_strategy

string

Defines how Forgejo/Gitea comments are handled for pipeline results.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

settings:
  forgejo:
    comment_strategy: "update"

AI Analysis Settings

AIAnalysisConfig

AI/LLM analysis configuration for automated CI/CD pipeline analysis.

Show AIAnalysisConfig Fields

ai.enabled

boolean

required

Controls whether AI analysis is active for this repository.

settings:
  ai:
    enabled: true

ai.provider

string

required

Specifies which LLM provider to use for analysis.Supported values:

openai - OpenAI (GPT models)
gemini - Google Gemini

settings:
  ai:
    provider: "openai"

ai.api_url

string

Optional base URL to override the default API endpoint of the LLM provider.Default values:

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

Use this to configure self-hosted LLM instances, proxy services, or alternative endpoints.

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

ai.secret_ref

Secret

required

References the Kubernetes secret containing the LLM provider API token.

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

ai.timeout_seconds

integer

Maximum time to wait for LLM analysis (default: 30).Valid range: 1-300 seconds

settings:
  ai:
    timeout_seconds: 60

ai.max_tokens

integer

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

settings:
  ai:
    max_tokens: 2000

ai.roles

[]AnalysisRole

required

Defines different analysis scenarios and their configurations. At least one role is required.

Show AnalysisRole Fields

roles[].name

string

required

Unique identifier for this analysis role.

roles[].prompt

string

required

Base prompt template sent to the LLM for analysis.

roles[].model

string

Specific LLM model to use for this role. If not specified, provider-specific defaults are used:

OpenAI: gpt-5-mini
Gemini: gemini-2.5-flash-lite

roles[].on_cel

string

CEL expression that determines when this role should be triggered.

roles[].output

string

Where the analysis results should be sent. Currently only pr-comment is supported (default).

roles[].context_items

ContextConfig

Defines what context data to include in the analysis.

Show ContextConfig Fields

context_items.commit_content

boolean

Include commit message and diff information.

context_items.pr_content

boolean

Include pull request title, description, and metadata.

context_items.error_content

boolean

Include error messages and failure summaries.

context_items.container_logs

ContainerLogsConfig

Configures inclusion of container/task logs.

Show ContainerLogsConfig Fields

container_logs.enabled

boolean

Controls whether container logs are included.

container_logs.max_lines

integer

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

settings:
  ai:
    roles:
      - name: "failure-analysis"
        prompt: "Analyze the following CI/CD failure and suggest fixes"
        model: "gpt-4"
        on_cel: "event_type == 'pull_request' && status == 'failed'"
        context_items:
          commit_content: true
          error_content: true
          container_logs:
            enabled: true
            max_lines: 100

Complete Example

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: 'event_type == "pull_request" && status == "failed"'
          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: 'event_type == "pull_request" && has_label("security-review")'
          context_items:
            commit_content: true
            pr_content: true

Settings Inheritance

Settings can be defined at both the global level (in the ConfigMap) and the repository level (in the Repository CR). Repository-level settings override global settings when both are present.

Repository Spec - Complete Repository specification
ConfigMap Reference - Global configuration settings

Custom Resources

Configuration

Settings Fields

Provider-Specific Settings

GitHub Settings

GitLab Settings

Forgejo/Gitea Settings

AI Analysis Settings

Complete Example

Settings Inheritance

Build docs developers (and LLMs) love

Custom Resources

Configuration

​Settings Fields

​Provider-Specific Settings

​GitHub Settings

​GitLab Settings

​Forgejo/Gitea Settings

​AI Analysis Settings

​Complete Example

​Settings Inheritance

​Related Resources

Build docs developers (and LLMs) love

Settings Fields

Provider-Specific Settings

GitHub Settings

GitLab Settings

Forgejo/Gitea Settings

AI Analysis Settings

Complete Example

Settings Inheritance

Related Resources