Advanced Repository Configuration

For Regular Users

本指南适用于需要高级 Repository CR 配置的普通用户，例如并发限制、源分支设置和自定义参数扩展。

本指南介绍 Repository Custom Resources 的高级配置选项，包括：

全局 Repository CR 用于自动配置继承（技术预览）
并发限制
源分支配置
自定义参数扩展

前提条件

已部署并运行 PAC 组件
已创建 Repository CR（参见 Configure Repository）
具有集群管理员或命名空间级权限

创建全局 Repository CR

Tech Preview Feature

全局 Repository CR 功能为技术预览功能，提供所有 Repository CR 的自动配置继承。

或者，您可以在 PAC 安装的命名空间（通常为 tekton-pipelines，或通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 配置）中创建一个全局 Repository CR。如果您在该命名空间中创建一个名为 pipelines-as-code 的 Repository CR，则您在其中指定的设置将自动应用于您创建的所有 Repository CR。

关键点：

名称：必须精确为 pipelines-as-code
命名空间：必须是 PAC 安装命名空间（例如 tekton-pipelines）
自动应用：设置自动应用于所有 Repository CR
技术预览：此功能为技术预览

示例：全局 Repository CR

在 PAC 命名空间中创建全局 Repository CR：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines  # PAC 安装命名空间
spec:
  git_provider:
    secret:
      name: gitlab-webhook-config
      key: provider.token
    webhook_secret:
      name: gitlab-webhook-config
      key: webhook.secret

应用 CR：

kubectl apply -f global-repository.yaml

行为：

您创建的所有 Repository CR 都将继承这些 git_provider 设置
单个 Repository CR 可以根据需要覆盖这些设置
仍需在每个 Repository CR 中指定 url 及其他仓库特定设置

示例：使用全局设置

使用上述全局 CR，您可以创建配置最简的单个 Repository CR：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-app-repo
  namespace: my-project
spec:
  url: "https://gitlab.com/user/my-app"
  # git_provider 设置继承自全局 CR

设置并发限制

并发限制有助于防止在大量事件同时触发流水线时资源耗尽。您可以设置一个仓库允许的最大并发 PipelineRun 数量。

配置并发限制

编辑您的 Repository CR，添加 concurrency_limit 字段：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

重要说明：

最小值为 1
如果未指定，则不限制并发 PipelineRun 数量
达到限制时，新事件将排队等待已有 PipelineRun 完成

示例用例

高流量仓库：限制并发运行数以防止集群过载：

spec:
  concurrency_limit: 3

资源密集型流水线：限制并发以确保每次运行有足够资源：

spec:
  concurrency_limit: 2

无限制（默认）：允许无限并发运行：

spec:
  # 未指定 concurrency_limit

验证并发限制

查看 Repository CR：

kubectl get repository my-repo -n project-pipelines -o yaml

示例输出（简略）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  concurrency_limit: 2

监控正在运行的 PipelineRuns：

kubectl get pipelineruns -n project-pipelines | grep Running

示例输出：

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Running
test-pipeline-yyyyy     1 minute ago   45s        Running

更改流水线定义的源分支

默认情况下，Pipelines-as-Code 会从触发事件所在的分支（例如 push 或 pull request 的分支）拉取 PipelineRun 定义。

您可以通过在 Repository 自定义资源中使用 spec.settings.pipelinerun_provenance 字段更改此行为。该设置控制 PipelineRun 定义从哪个分支拉取。

配置 PipelineRun 定义来源

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
  settings:
    pipelinerun_provenance: "default_branch"

pipelinerun_provenance 支持的值：

source：默认行为。PipelineRun 定义从触发事件所在分支拉取。
default_branch：PipelineRun 定义从 Git 提供商配置的仓库默认分支拉取（例如 main、master 或 trunk）。

安全性优势

允许用户将 PipelineRun 定义的来源指定为默认分支，是另一层安全保障。它确保只有有权合并提交到默认分支的用户，才能更改 PipelineRun 定义并访问基础设施。

防止恶意流水线更改：流水线定义必须合并到默认分支后才能执行。
强制审查流程：所有流水线更改都经过标准的合并/审查流程。
流水线行为一致：所有运行均使用默认分支的相同流水线定义。

配置对比

配置	分支来源	安全级别	使用场景
`settings.pipelinerun_provenance: "source"`	触发事件分支	标准	开发、测试
`settings.pipelinerun_provenance: "default_branch"`	仓库默认分支	高	生产、安全要求较高场景

注意：根据 Red Hat OpenShift Pipelines 文档，推荐使用 default_branch 设置作为安全措施，以确保流水线更改在合并审查过程中得到最大程度的验证。

自定义参数扩展

您可以在 Repository CR 中定义自定义参数，这些参数将在为该仓库创建的所有 PipelineRun 中展开。此功能适用于为所有流水线设置通用值。

定义自定义参数

在 Repository CR 的 spec.params 字段中添加参数：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  - name: namespace
    value: "production"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token

在流水线中使用自定义参数

重要：Repository CR 参数使用 PAC 变量语法 {{ param }}，而非 Tekton 的 $(params.param) 语法。

PAC 变量 ({{ variable }})：PAC 在创建 PipelineRun 之前替换这些变量，包括：
- Repository CR 中 spec.params 的参数（如 {{ environment }}、{{ cluster-name }}）
- PAC 内置变量（如 {{ revision }}、{{ repo_url }}、{{ source_branch }}）
Tekton 参数 ($(params.param))：Tekton 在 PipelineRun 执行时解析，引用 PipelineRun 自身的 spec.params。

在 PipelineRun 定义中使用 PAC 变量语法引用 Repository CR 参数：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: deploy-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  params:
  - name: environment
    value: "{{ environment }}"  # PAC 变量 - 替换为 Repository CR 参数值
  - name: cluster-name
    value: "{{ cluster-name }}"  # PAC 变量 - 替换为 Repository CR 参数值
  - name: namespace
    value: "{{ namespace }}"  # PAC 变量 - 替换为 Repository CR 参数值
  - name: revision
    value: "{{ revision }}"  # PAC 内置变量 - 替换为提交 SHA
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            echo "Deploying to $(params.environment)"  # 脚本中使用 Tekton 参数语法
            echo "Cluster: $(params.cluster-name)"
            echo "Namespace: $(params.namespace)"
            echo "Commit: $(params.revision)"

工作原理：

PipelineRun 创建前：PAC 替换所有 {{ variable }} 语法为 Repository CR 参数和内置变量的实际值
PipelineRun 创建时：PAC 创建的 PipelineRun 中所有变量已被替换
执行时：Tekton 通过读取 PipelineRun 的 spec.params 解析 $(params.xxx) 语法

示例转换：

Git 仓库中：value: "{{ environment }}"
PAC 替换为：value: "production"（来自 Repository CR 参数）
创建的 PipelineRun 中为：- name: environment / value: "production"
任务脚本中使用：$(params.environment) → Tekton 解析为 "production"

参数优先级

参数展开顺序（优先级从高到低）：

PipelineRun 参数：PipelineRun 中显式定义的参数
Repository 参数：Repository CR 中定义的参数
动态变量：PAC 动态变量（如 {{ revision }}、{{ repo_url }}）

示例：环境特定配置

使用 Repository 参数配置不同环境：

生产环境仓库：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: prod-repo
  namespace: production
spec:
  url: "https://gitlab.com/user/prod-repo"
  params:
  - name: environment
    value: "production"
  - name: api-url
    value: "https://api.production.example.com"
  - name: registry
    value: "registry.production.example.com"

预发布环境仓库：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: staging-repo
  namespace: staging
spec:
  url: "https://gitlab.com/user/staging-repo"
  params:
  - name: environment
    value: "staging"
  - name: api-url
    value: "https://api.staging.example.com"
  - name: registry
    value: "registry.staging.example.com"

两个仓库可以使用相同的流水线定义，参数自动从 Repository CR 填充。

组合高级功能

您可以在单个 Repository CR 中组合所有高级功能：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: advanced-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  concurrency_limit: 5
  params:
  - name: environment
    value: "production"
  - name: cluster-name
    value: "prod-cluster"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

最佳实践

1. 并发限制

设置合适的限制：考虑集群资源和流水线资源需求
监控使用情况：当限制过低时，注意排队事件
动态调整：高流量时增加限制，节约资源时减少限制

2. 源分支配置

使用稳定分支：从稳定分支（如 main）拉取流水线定义
测试流水线更改：在功能分支测试流水线更改后再合并到源分支
文档说明：清晰记录哪个分支包含流水线定义

3. 自定义参数

使用有意义的名称：选择清晰、描述性的参数名
保持值简单：参数值使用简单字符串
文档说明：记录每个参数的作用及使用场景
避免存储密钥：不要在 Repository 参数中存储密钥，使用 Kubernetes Secret

故障排查

并发限制不起作用

确认限制已设置：

kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.concurrency_limit}'

示例输出：

2 # 这是并发限制

检查是否有排队事件：查看是否有事件等待 PipelineRun 完成

查看 PAC 控制器日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep concurrency  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

示例输出：

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Concurrency limit reached","repository":"my-repo","limit":2,"running":2}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun queued","repository":"my-repo","reason":"concurrency_limit"}

参数未展开

确认参数已定义：

kubectl get repository my-repo -n project-pipelines -o jsonpath='{.spec.params}'

检查参数语法：确保使用的是 {{ param }} 语法引用 Repository CR 参数，而非 $(params.param)

验证变量替换：查看创建的 PipelineRun 是否被 PAC 替换变量：

kubectl get pipelinerun <run-name> -n <namespace> -o yaml | grep -A 5 "params:"

检查 PipelineRun：确认参数未被 PipelineRun 定义中覆盖

后续步骤

Configure Repository - 基础仓库配置
Maintain Pipeline Code - 流水线定义指南
Manage PipelineRuns - PipelineRun 管理
Common Issues - 故障排查指南

#Advanced Repository Configuration

#目录

#前提条件

#创建全局 Repository CR

#示例：全局 Repository CR

#示例：使用全局设置

#设置并发限制

#配置并发限制

#示例用例

#验证并发限制

#更改流水线定义的源分支

#配置 PipelineRun 定义来源

#安全性优势

#配置对比

#自定义参数扩展

#定义自定义参数

#在流水线中使用自定义参数

#参数优先级

#示例：环境特定配置

#组合高级功能

#最佳实践

#1. 并发限制

#2. 源分支配置

#3. 自定义参数

#故障排查

#并发限制不起作用

#参数未展开

#后续步骤

Advanced Repository Configuration

目录

前提条件

创建全局 Repository CR

示例：全局 Repository CR

示例：使用全局设置

设置并发限制

配置并发限制

示例用例

验证并发限制

更改流水线定义的源分支

配置 PipelineRun 定义来源

安全性优势

配置对比

自定义参数扩展

定义自定义参数

在流水线中使用自定义参数

参数优先级

示例：环境特定配置

组合高级功能

最佳实践

1. 并发限制

2. 源分支配置

3. 自定义参数

故障排查

并发限制不起作用

参数未展开

后续步骤