Repository Spec

On this page

Fields
Complete example

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

# 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.

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

# 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.

spec:
  concurrency_limit: 5

# 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

# 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)

git_provider:
  type: github

# 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).

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

# 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.

git_provider:
  user: "pac-bot"

# 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

# secret.name string required

Name of the Kubernetes secret.

# secret.key string

Key within the secret containing the value.

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

# 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.

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

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

# 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

# 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.

# 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

# secret.name string required

Name of the Kubernetes secret.

# secret.key string

Key within the secret containing the value.

# 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.

# 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.

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

# params []Params

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

Show Params Fields

# params[].name string required

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

# 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.

# 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

# secret.name string required

Name of the Kubernetes secret.

# secret.key string

Key within the secret containing the value.

# 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.

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

# settings Settings

Configures repository-level settings, including authorization policies, provider-specific behavior, and provenance settings. See Settings Reference for detailed documentation.

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

Complete example

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"
    policy:
      ok_to_test:
        - "maintainer-user"
        - "trusted-contributor"
      pull_request:
        - "external-contributor"
    github:
      comment_strategy: "update"

Repository CR Repository Status