高级 Repository 配置

针对普通用户

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

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

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

前提条件

已部署并运行 PAC 组件
已创建 Repository CR（请参阅指南）
集群管理员或命名空间级权限

创建全局 Repository CR

技术预览功能

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

或者，你可以在安装 PAC 的命名空间中创建一个全局 Repository CR（通常为 tekton-pipelines，或者通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行配置）。如果你在该命名空间中创建一个名为 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 installation namespace
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 settings are inherited from the global CR

设置并发限制

并发限制有助于在大量事件同时触发 pipeline 时防止资源耗尽。你可以为某个仓库设置可同时运行的 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

资源密集型 pipeline：限制并发数量，以确保每次运行都有足够资源：

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

监控正在运行的 PipelineRun：

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

更改 Pipeline 定义的源分支

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

你可以通过在 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 定义并获取基础设施访问权限。

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

配置对比

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

注意：当 pipeline 定义必须先通过仓库的合并审查流程，才能影响后续运行时，请使用 default_branch。

自定义参数展开

你可以在 Repository CR 中定义自定义参数，这些参数会在为该仓库创建的所有 PipelineRun 中展开。这对于在所有 pipeline 之间设置通用值非常有用。

定义自定义参数

将参数添加到 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

在 pipeline 中使用自定义参数

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

PAC 变量（{{ variable }}）：PAC 会在创建 PipelineRun 之前替换这些变量。包括：
- 来自 spec.params 的 Repository CR 参数（例如 {{ 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 variable - replaced with Repository CR param value
  - name: cluster-name
    value: "{{ cluster-name }}"  # PAC variable - replaced with Repository CR param value
  - name: namespace
    value: "{{ namespace }}"  # PAC variable - replaced with Repository CR param value
  - name: revision
    value: "{{ revision }}"  # PAC built-in variable - replaced with commit SHA
  pipelineSpec:
    tasks:
    - name: deploy
      taskSpec:
        steps:
        - name: deploy
          image: deploy-tool:latest
          script: |
            echo "Deploying to $(params.environment)"  # Tekton parameter syntax in script
            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"
Task 脚本使用：$(params.environment) → Tekton 解析为 "production"

参数优先级

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

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

示例：环境特定配置

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

生产环境 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"

预发布环境 Repository：

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"

这两个仓库都可以使用相同的 pipeline 定义，参数会从 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. 并发限制

设置合适的限制：考虑你的集群资源和 pipeline 资源需求
监控使用情况：当限制过低时，注意观察排队中的事件
动态调整：在高流量时段提高限制，在需要节省资源时降低限制

2. 源分支配置

使用稳定分支：从稳定分支（例如 main）获取 pipeline 定义
测试 pipeline 更改：在合并到源分支之前，先在功能分支中测试 pipeline 更改
记录更改：清楚地记录包含 pipeline 定义的是哪个分支

3. 自定义参数

使用有意义的名称：选择清晰、具描述性的参数名称
保持值简单：参数尽量使用简单的字符串值
记录参数：说明每个参数的作用以及何时使用
避免敏感信息：不要将密钥存储在 Repository 参数中；请改用 Kubernetes Secrets

故障排查

并发限制不生效

验证限制是否已设置：

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

示例输出：

2 # 这是并发限制

检查是否有排队中的事件：查看是否存在正在等待 PipelineRun 完成的事件

验证 PAC controller 日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep concurrency  # Replace <pac-namespace> with your actual namespace (default: 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 定义中参数是否被覆盖

下一步

指南 - 基础仓库设置流程
在 Git 中定义 PipelineRun - PipelineRun 文件和触发器注解
管理 PipelineRun - PipelineRun 管理
常见问题 - 故障排查指南

#高级 Repository 配置

#目录

#前提条件

#创建全局 Repository CR

#示例：全局 Repository CR

#示例：使用全局设置

#设置并发限制

#配置并发限制

#示例用例

#验证并发限制

#更改 Pipeline 定义的源分支

#配置 PipelineRun 定义来源

#安全优势

#配置对比

#自定义参数展开

#定义自定义参数

#在 pipeline 中使用自定义参数

#参数优先级

#示例：环境特定配置

#组合使用高级功能

#最佳实践

#1. 并发限制

#2. 源分支配置

#3. 自定义参数

#故障排查

#并发限制不生效

#参数未展开

#下一步

高级 Repository 配置

目录

前提条件

创建全局 Repository CR

示例：全局 Repository CR

示例：使用全局设置

设置并发限制

配置并发限制

示例用例

验证并发限制

更改 Pipeline 定义的源分支

配置 PipelineRun 定义来源

安全优势

配置对比

自定义参数展开

定义自定义参数

在 pipeline 中使用自定义参数

参数优先级

示例：环境特定配置

组合使用高级功能

最佳实践

1. 并发限制

2. 源分支配置

3. 自定义参数

故障排查

并发限制不生效

参数未展开

下一步