高级 Repository 配置

适用于普通用户

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

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

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

前提条件

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

创建全局 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 时导致资源耗尽。你可以为某个仓库设置允许运行的最大并发 PipelineRuns 数量。

配置并发限制

编辑你的 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
如果未指定，则并发 PipelineRuns 不受限制
达到限制后，新事件会进入队列，直到某个 PipelineRun 完成

使用场景示例

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

spec:
  concurrency_limit: 3

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

spec:
  concurrency_limit: 2

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

spec:
  # concurrency_limit not specified

验证并发限制

检查 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

更改 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 provider 中配置的仓库默认分支获取（例如 main、master 或 trunk）。

安全优势

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

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

配置对比

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

注意：根据 Red Hat OpenShift Pipelines 文档，建议将 default_branch 设置作为安全措施，以确保在合并审查过程中对 pipeline 更改进行最大程度的验证。

自定义参数展开

你可以在 Repository CR 中定义自定义参数，这些参数会在为该仓库创建的所有 PipelineRuns 中展开。这对于在所有 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 variables（{{ variable }}）：PAC 会在创建 PipelineRun 之前替换这些变量。其中包括：
- 来自 spec.params 的 Repository CR 参数（例如 {{ environment }}、{{ cluster-name }}）
- PAC 内置变量（例如 {{ revision }}、{{ repo_url }}、{{ source_branch }}）
Tekton parameters（$(params.param)）：Tekton 会在 PipelineRun 执行期间解析这些参数。它们引用的是 PipelineRun 自身的 spec.params。

请使用 PAC 变量语法在你的 PipelineRun 定义中引用 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 params：在 PipelineRun 中显式定义的参数
Repository params：在 Repository CR 中定义的参数
动态变量：PAC 动态变量（例如 {{ revision }}、{{ repo_url }}）

示例：按环境区分的配置

使用 Repository params 配置不同环境：

生产仓库：

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"

这两个仓库都可以使用相同的 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 params 中；请改用 Kubernetes Secrets

故障排除

并发限制未生效

验证是否已设置限制：

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

示例输出：

2 # This is the concurrency limit

检查是否有排队事件：查找正在等待 PipelineRuns 完成的事件

验证 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 定义中覆盖了参数

下一步

Configure Repository - 基本仓库设置
Maintain Pipeline Code - Pipeline 定义指南
Manage PipelineRuns - PipelineRun 管理
Common Issues - 故障排除指南

#高级 Repository 配置

#目录

#前提条件

#创建全局 Repository CR

#示例：全局 Repository CR

#示例：使用全局设置

#设置并发限制

#配置并发限制

#使用场景示例

#验证并发限制

#更改 Pipeline 定义的源分支

#配置 PipelineRun 定义来源

#安全优势

#配置对比

#自定义参数展开

#定义自定义参数

#在 Pipeline 中使用自定义参数

#参数优先级

#示例：按环境区分的配置

#组合使用高级功能

#最佳实践

#1. 并发限制

#2. 源分支配置

#3. 自定义参数

#故障排除

#并发限制未生效

#参数未展开

#下一步

高级 Repository 配置

目录

前提条件

创建全局 Repository CR

示例：全局 Repository CR

示例：使用全局设置

设置并发限制

配置并发限制

使用场景示例

验证并发限制

更改 Pipeline 定义的源分支

配置 PipelineRun 定义来源

安全优势

配置对比

自定义参数展开

定义自定义参数

在 Pipeline 中使用自定义参数

参数优先级

示例：按环境区分的配置

组合使用高级功能

最佳实践

1. 并发限制

2. 源分支配置

3. 自定义参数

故障排除

并发限制未生效

参数未展开

下一步