Repository Custom Resource

Overview

The Repository Custom Resource (CR) is the central configuration object that connects your Git repository to Pipelines-as-Code. It tells PAC:

Which repository events to handle
Where to run PipelineRuns (namespace)
How to authenticate with the Git provider
Custom parameters and settings

A Repository CR must be created in your project namespace (not in the pipelines-as-code or openshift-pipelines namespace).

Basic Configuration

Create a Repository CR

The minimal configuration requires only a repository URL:

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repository
  namespace: my-project
spec:
  url: "https://github.com/owner/repo"

Apply the configuration

Using kubectl

kubectl create -f repository.yaml

Using tkn pac CLI

tkn pac create repository

Follow the interactive prompts to configure your repository.

Inline with kubectl

cat <<EOF | kubectl create -n my-project -f-
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repository
spec:
  url: "https://github.com/owner/repo"
EOF

Repository Spec Fields

URL

spec.url

string

required

The full HTTP/HTTPS URL of your Git repository

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

Pipelines-as-Code uses a Mutating Admission Webhook to enforce one Repository CRD per URL cluster-wide. This prevents repository hijacking in multi-tenant clusters.

Git Provider Configuration

spec.git_provider

object

Git provider authentication and API configuration

spec:
  git_provider:
    type: "github"  # github, gitlab, bitbucket-cloud, bitbucket-datacenter, forgejo, gitea
    url: "https://api.github.com"  # API endpoint
    user: "git"  # Username for authentication
    secret:
      name: "github-webhook-secret"
      key: "token"
    webhook_secret:
      name: "webhook-secret"
      key: "secret"

Supported Git Provider Types

GitHub
GitLab
Bitbucket Cloud
Bitbucket Data Center
Forgejo/Gitea

spec:
  git_provider:
    type: "github"
    url: "https://api.github.com"  # or GitHub Enterprise URL
    secret:
      name: "github-token"
      key: "token"

spec:
  git_provider:
    type: "gitlab"
    url: "https://gitlab.com"  # or self-hosted GitLab URL
    secret:
      name: "gitlab-token"
      key: "token"

spec:
  git_provider:
    type: "bitbucket-cloud"
    user: "username"
    secret:
      name: "bitbucket-token"
      key: "token"

spec:
  git_provider:
    type: "bitbucket-datacenter"
    url: "https://bitbucket.mycompany.com"
    secret:
      name: "bitbucket-token"
      key: "token"

spec:
  git_provider:
    type: "forgejo"  # or "gitea" (alias)
    url: "https://forgejo.mycompany.com"
    secret:
      name: "forgejo-token"
      key: "token"

Concurrency Limit

spec.concurrency_limit

integer

Maximum number of concurrent PipelineRuns for this repository

spec:
  concurrency_limit: 3

When multiple PipelineRuns match an event, they run in alphabetical order by name. Only the specified number run concurrently; others queue.

Example: With 3 PipelineRuns and concurrency_limit: 1:

# .tekton/a-build.yaml (runs first)
# .tekton/b-test.yaml (queued)
# .tekton/c-lint.yaml (queued)

For Kubernetes-native queuing, consider using Kueue via the experimental tekton-kueue integration.

Incoming Webhooks

spec.incoming

array

Configure external webhook triggers

spec:
  incoming:
    - type: "webhook-url"
      secret:
        name: "webhook-secret"
        key: "token"
      params:
        - "param1"
        - "param2"
      targets:
        - "main"
        - "develop"

Custom Parameters

spec.params

array

Define repository-level parameters available in PipelineRuns

spec:
  params:
    - name: "image_registry"
      value: "quay.io/myorg"
    - name: "database_url"
      secret_ref:
        name: "db-credentials"
        key: "url"
    - name: "deploy_to_staging"
      value: "true"
      filter: 'event == "pull_request"'

String Value
Secret Reference
Filtered Parameter

params:
  - name: "environment"
    value: "staging"

params:
  - name: "api_token"
    secret_ref:
      name: "api-credentials"
      key: "token"

params:
  - name: "docker_registry"
    value: "registry.staging.example.com"
    filter: 'event == "pull_request"'

This parameter is only available when the event type is pull_request.

Settings Configuration

spec.settings

object

Repository-specific operational settings

PipelineRun Provenance

spec.settings.pipelinerun_provenance

string

Controls where PipelineRun definitions are fetched from

source (default): Fetch from the event’s source branch/SHA
default_branch: Always fetch from the repository’s default branch

spec:
  settings:
    pipelinerun_provenance: "default_branch"

Using default_branch adds a security layer: only users who can merge to the default branch can modify PipelineRuns.

GitHub Settings

spec.settings.github

object

GitHub-specific configuration

Comment Strategy

spec:
  settings:
    github:
      comment_strategy: "update"  # "", "update", or "disable_all"

"" (default): Create new comments for each PipelineRun status update
"update": Update a single comment per PipelineRun
"disable_all": No status comments (errors still commented)

GitHub Token Scoping

spec.settings.github_app_token_scope_repos

array

Extend GitHub App token scope to additional repositories

spec:
  settings:
    github_app_token_scope_repos:
      - "owner/project"
      - "owner1/*"  # Glob pattern

All repositories must exist in the same namespace.

Prerequisites:

Set secret-github-app-token-scoped: "false" in the pipelines-as-code ConfigMap
List additional repositories (exact names or glob patterns)

Global Configuration (admin-only):

apiVersion: v1
kind: ConfigMap
metadata:
  name: pipelines-as-code
  namespace: pipelines-as-code
data:
  secret-github-app-token-scoped: "false"
  secret-github-app-scope-extra-repos: "owner2/project2, owner3/*"

Combined Example: Global config:

data:
  secret-github-app-scope-extra-repos: "owner2/project2, owner3/project3"

Repository CR:

spec:
  settings:
    github_app_token_scope_repos:
      - "owner/project"
      - "owner1/project1"

Token is scoped to: owner/project, owner1/project1, owner2/project2, owner3/project3, and the original repository.

GitLab Settings

spec.settings.gitlab

object

GitLab-specific configuration

spec:
  settings:
    gitlab:
      comment_strategy: "disable_all"  # "", "update", or "disable_all"

GitLab updates commit statuses via the API when possible. Comments are only posted when:

Both source and target project status updates fail (insufficient permissions)
comment_strategy is not "disable_all"

Forgejo/Gitea Settings

spec.settings.forgejo

object

Forgejo/Gitea-specific configuration

spec:
  settings:
    forgejo:
      user_agent: "my-custom-agent"  # Custom User-Agent header
      comment_strategy: "update"  # "", "update", or "disable_all"

Custom User-Agent: Useful when the Forgejo instance is behind AI scraping protection (e.g., Anubis proxy) that blocks requests without a recognized User-Agent.

Authorization Policy

spec.settings.policy

object

Control who can trigger PipelineRuns

spec:
  settings:
    policy:
      ok_to_test:
        - "maintainer1"
        - "maintainer2"
      pull_request:
        - "contributor1"
        - "contributor2"

ok_to_test: Users who can approve external PRs with /ok-to-test
pull_request: External contributors explicitly allowed to run CI

See the Authorization Policy guide for details.

AI Analysis

spec.settings.ai

object

Enable AI-powered pipeline failure analysis

spec:
  settings:
    ai:
      enabled: true
      provider: "openai"
      model: "gpt-4"

Complete Examples

GitHub Repository with Settings

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-app
  namespace: my-project
spec:
  url: "https://github.com/myorg/my-app"
  concurrency_limit: 2
  params:
    - name: "image_registry"
      value: "quay.io/myorg"
    - name: "deploy_env"
      value: "staging"
      filter: 'event == "pull_request"'
  settings:
    pipelinerun_provenance: "default_branch"
    github:
      comment_strategy: "update"
    policy:
      ok_to_test:
        - "team-lead"
        - "senior-dev"

GitLab Repository with Webhook

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: gitlab-project
  namespace: ci-namespace
spec:
  url: "https://gitlab.com/mygroup/myproject"
  git_provider:
    type: "gitlab"
    url: "https://gitlab.com"
    secret:
      name: "gitlab-token"
      key: "token"
    webhook_secret:
      name: "gitlab-webhook-secret"
      key: "secret"
  settings:
    gitlab:
      comment_strategy: "update"

Self-hosted Forgejo Repository

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: forgejo-repo
  namespace: dev-team
spec:
  url: "https://git.mycompany.com/team/project"
  git_provider:
    type: "forgejo"
    url: "https://git.mycompany.com"
    secret:
      name: "forgejo-credentials"
      key: "token"
  settings:
    forgejo:
      user_agent: "mycompany-ci-agent"
      comment_strategy: "disable_all"

Multi-Repository Token Scoping

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: mono-repo
  namespace: platform
spec:
  url: "https://github.com/myorg/mono-repo"
  settings:
    github_app_token_scope_repos:
      - "myorg/shared-tasks"      # Access shared task definitions
      - "myorg/infrastructure/*"   # Access all infra repos
    pipelinerun_provenance: "default_branch"
  params:
    - name: "shared_task_repo"
      value: "https://github.com/myorg/shared-tasks"

Target Namespace Annotation

For added security, explicitly target a namespace in your PipelineRun:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/target-namespace: "my-namespace"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"

This prevents bad actors from hijacking PipelineRun execution to unauthorized namespaces.

Troubleshooting

Repository not matching events

Verify Repository CR exists

kubectl get repository -n my-namespace

Check URL matches exactly

kubectl get repository my-repo -n my-namespace -o jsonpath='{.spec.url}'

URL must match the webhook payload exactly (including .git suffix if present).

Check webhook configuration

Verify the webhook secret is correct:

kubectl get secret webhook-secret -n my-namespace -o yaml

Check PAC controller logs

kubectl logs -n pipelines-as-code deployment/pipelines-as-code-controller

Token scoping failures

If GitHub token scoping fails:

failed to scope GitHub token as repo with pattern owner/repo does not exist in namespace my-namespace

Solutions:

Ensure all repositories exist in the same namespace as the Repository CR
Verify the GitHub App is installed for all specified repositories
Check glob patterns match correctly

Next Steps

Creating Pipelines

Learn how to create PipelineRun definitions

Event Matching

Configure advanced event matching with annotations

Running Pipelines

Understand execution, permissions, and monitoring

Custom Parameters

Define and use custom parameters in pipelines

Getting Started

Installation

Git Provider Setup

Core Guides

Advanced Features

Operations

Overview

Basic Configuration

Repository Spec Fields

URL

Git Provider Configuration

Supported Git Provider Types

Concurrency Limit

Incoming Webhooks

Custom Parameters

Settings Configuration

PipelineRun Provenance

GitHub Settings

Comment Strategy

GitHub Token Scoping

GitLab Settings

Forgejo/Gitea Settings

Authorization Policy

AI Analysis

Complete Examples

GitHub Repository with Settings

GitLab Repository with Webhook

Self-hosted Forgejo Repository

Multi-Repository Token Scoping

Target Namespace Annotation

Troubleshooting

Repository not matching events

Token scoping failures

Next Steps

Creating Pipelines

Event Matching

Running Pipelines

Custom Parameters

Build docs developers (and LLMs) love

Getting Started

Installation

Git Provider Setup

Core Guides

Advanced Features

Operations

​Overview

​Basic Configuration

​Repository Spec Fields

​URL

​Git Provider Configuration

​Supported Git Provider Types

​Concurrency Limit

​Incoming Webhooks

​Custom Parameters

​Settings Configuration

​PipelineRun Provenance

​GitHub Settings

​Comment Strategy

​GitHub Token Scoping

​GitLab Settings

​Forgejo/Gitea Settings

​Authorization Policy

​AI Analysis

​Complete Examples

​GitHub Repository with Settings

​GitLab Repository with Webhook

​Self-hosted Forgejo Repository

​Multi-Repository Token Scoping

​Target Namespace Annotation

​Troubleshooting

​Repository not matching events

​Token scoping failures

​Next Steps

Creating Pipelines

Event Matching

Running Pipelines

Custom Parameters

Build docs developers (and LLMs) love

Overview

Basic Configuration

Repository Spec Fields

URL

Git Provider Configuration

Supported Git Provider Types

Concurrency Limit

Incoming Webhooks

Custom Parameters

Settings Configuration

PipelineRun Provenance

GitHub Settings

Comment Strategy

GitHub Token Scoping

GitLab Settings

Forgejo/Gitea Settings

Authorization Policy

AI Analysis

Complete Examples

GitHub Repository with Settings

GitLab Repository with Webhook

Self-hosted Forgejo Repository

Multi-Repository Token Scoping

Target Namespace Annotation

Troubleshooting

Repository not matching events

Token scoping failures

Next Steps