#高级 Repository 配置

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

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

#前提条件

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

#创建全局 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
• Tech Preview：这是一个 Technology Preview 功能

#示例：全局 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 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

监控正在运行的 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 custom resource 中使用 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 定义。

#配置对比

注意：根据 Red Hat OpenShift Pipelines documentation，建议将 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 变量（{{ 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)"

工作原理：

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

转换示例：

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

#参数优先级

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

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

#示例：按环境配置

使用 Repository params 配置不同环境：

生产环境 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. 自定义参数

• 使用有意义的名称：选择清晰、具有描述性的参数名称
• 保持值简单：参数尽量使用简单的字符串值
• 记录参数：说明每个参数的作用及其使用时机
• 避免使用 secret：不要将 secret 存储在 Repository params 中；应改用 Kubernetes Secrets

#故障排除

#并发限制未生效

1. 确认已设置限制：

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

示例输出：

2 # This is the concurrency limit

2. 检查是否存在排队事件：查找正在等待 PipelineRun 完成的事件

3. 验证 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"}

#参数未展开

1. 确认已定义参数：

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

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

3. 验证变量替换：检查创建出来的 PipelineRun，确认 PAC 是否已替换变量：

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

4. 检查 PipelineRun：确认参数是否在 PipelineRun 定义中被覆盖

#下一步

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