#核心概念

本页介绍 PAC 在 Tekton 之上引入的资源、运行时组件和触发模型。若要快速了解整体概览和适用对象映射，请参阅 简介。

#架构

PAC 在集群中运行三个 controller，并对 Git provider 传递的事件作出响应：

• PAC Webhook 是暴露给 Git provider 的 HTTP 监听器。它会使用共享的 webhook secret 验证每个传入请求，并将已验证的 payload 转发给 controller。任何验证失败的内容都会在接触 Tekton 之前被丢弃。
• PAC Controller 负责处理“这个事件应该运行什么”的逻辑。它会查找匹配的 Repository 资源，从事件所引用的 ref 获取 .tekton/ manifests，使用 trigger 注解进行过滤，展开变量，并创建 PipelineRuns。
• PAC Watcher 跟踪 PAC 创建的 PipelineRuns，并将其状态回报给 Git provider——具体形式可以是 GitHub Check Run、commit status 或 comment，取决于 provider。

这三个组件都运行在 PAC namespace 中（默认值：tekton-pipelines）。Tekton Operator 会根据 TektonConfig 派生出的 OpenShiftPipelinesAsCode CR 来部署它们——请参阅 Operator 如何管理 PAC。

#Repository 资源

Repository 是你针对每个 Git repository 维护的唯一资源。它将一个 Git URL 绑定到一个 Kubernetes namespace：来自该 URL 的事件会在这个 namespace 中生成 PipelineRuns，而且只会在这个 namespace 中生成。多个 Repository 资源可以指向同一个 Git URL，但只能位于不同的 namespace 中——这通常用于“每个环境一个 team namespace”的布局。

Repository 不包含任何 pipeline 定义。pipeline 定义保存在 Git repository 本身中，即 .tekton/ 目录下。删除 Repository 只会停止 PAC 创建新的 PipelineRuns；已经创建的运行会保留原样。

#关键 spec 字段

示例（通过 Webhook 的 GitLab）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.com/group/project
  git_provider:
    type: gitlab
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

在 GitHub App 模式下，会省略整个 git_provider 块。PAC 使用集群范围的 App 凭据进行认证，因此不需要每个 repository 单独配置 token 和 webhook secret。在此模式下不会使用自动 webhook 注册，因为 webhook 投递由 GitHub App 负责。

#两种集成模式

Git provider 有两种向 PAC 投递事件的方式，而 Repository spec 会随着模式不同而变化。

• GitHub App 模式 — 在 GitHub organization 或 user 上一次性安装 GitHub App。该 App 在 organization 级别负责 webhook 和凭据。安装覆盖到的每个 repository 都可以使用最小化的 Repository 进行接入（只需 spec.url）。状态通过 GitHub Checks API 报告。仅适用于 GitHub。
• Webhook 模式 — 每个 repository 单独配置 Personal Access Token 和 webhook。Repository 会引用一个 Kubernetes Secret，其中包含 token 和 webhook secret，并且必须将 spec.git_provider.type 设置为 github 或 gitlab，才能进行自动 webhook 注册。状态会作为 commit status 报告。本文档涵盖 GitHub Webhook 模式和 GitLab Webhook 模式。

在同一个 Repository 上，这两种模式是互斥的。每个 provider 的端到端流程请参阅 指南。

#.tekton/ 目录约定

PAC 从 Git repository 根目录下的 .tekton/ 目录读取 PipelineRun manifests。约定如下：

• 会扫描 .tekton/ 下所有 .yaml 或 .yml 文件。每个文件中可以包含多个 PipelineRun，且每个 repository 可以有多个文件。
• manifests 会从事件触发时所对应的 ref 读取——pull request 读取源分支，push 读取被推送的分支，tag push 读取该 tag 的 ref。
• 每个 PipelineRun 都会独立评估。单个事件可能生成零个、一个或多个 PipelineRun，具体取决于匹配到多少 manifests。
• 适用标准 PipelineRun 结构；PAC 只是额外添加 annotations 和 variables。Task 可以是内联的（pipelineSpec）、引用集群中已有的 Pipeline（pipelineRef），也可以在提交时从 artifacthub-shim 提供的 DevOps Hub catalog 或远程 URL 中解析。

#事件生命周期

有几个值得注意的特性：

• webhook 处的验证步骤是 fail-closed：签名无效的事件不会到达 controller、Repository controller 或集群。
• controller 会在创建任何 Kubernetes 对象之前完成过滤和变量展开，因此不匹配的事件不会生成 PipelineRun，也不会留下除日志行之外的任何痕迹。
• 状态报告是异步的，并会在 PipelineRun 状态发生变化时触发，包括完成以及单个步骤失败时（前提是 provider 支持按步骤报告）。

#触发模型

PipelineRun manifests 通过 metadata.annotations 上的注解声明它们关注的事件。controller 会使用这些注解对 manifests 与事件进行过滤。

#事件类型

#注解语法

一对简单的匹配器（on-event + on-target-branch）足以满足大多数场景。对于组合条件（“仅当 PR head 匹配 feature/* 且变更文件包含 api/** 时”），请改用 CEL 表达式：

annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" &&
    source_branch.startsWith("feature/") &&
    files.modified.exists(f, f.startsWith("api/"))

CEL 程序可接收 event、event_title、target_branch、source_branch、body、headers，以及带有 all、added、deleted、modified 和 renamed 列表的 files 对象。

完整的注解语法、更多 CEL 示例以及冲突解决规则，请参阅 在 Git 中定义 PipelineRuns。

#变量与解析

在创建 PipelineRun 时，PAC 会根据事件 payload 展开一小组占位符。其值在创建后会保留在 PipelineRun 中，不会重新计算。

PAC 还可以在提交时内联 Task 和 Pipeline manifests——包括通过路径引用的本地文件、通过短名称引用的 DevOps Hub 资源，以及远程 URL。解析器会在创建 PipelineRun 之前运行，因此生成的对象是自包含的。语法和支持的数据源请参阅 PAC Resolver。

#状态报告

PAC 通过三种渠道将 PipelineRun 状态回报给 Git provider，会根据 provider 和集成模式自动选择：

• GitHub Checks API — 用于 GitHub App 模式。每个 PipelineRun 都会显示为一个 Check Run，并带有按步骤输出以及附加到 commit 上的“in progress / success / failure”徽标。
• Commit statuses — 用于 GitHub Webhook 模式和 GitLab。会在 commit 上发布一条简短状态，并在相关场景下发布到 PR / MR。
• Comment — 对于失败情况，会在 PR / MR 上添加一条 comment，其中包含 PipelineRun 名称和指向集群的链接。具体格式取决于 provider。

状态报告中嵌入的集群侧 URL 可以通过 TektonConfig 中的 custom-console-url-* 设置进行自定义；请参阅 管理 PAC 组件。注意，custom-console-url-namespace-vars 属于 options.configMaps，而不是 settings——原因请参阅 每项设置应放在哪里。

#并发与取消

默认情况下，每个匹配事件都会立即创建其 PipelineRun。有两个设置会影响这种行为：

• Repository.spec.concurrency_limit 限制该 repository 中可并行运行的 PipelineRun 数量。超出的运行会排队，并在较早的运行完成后启动。
• PipelineRun 上的 pipelinesascode.tekton.dev/cancel-in-progress 注解会指示 PAC：在启动新的运行之前，取消任何与同一事件组匹配的旧运行（例如同一个 PR）。当对 PR 进行新的 push 时，需要使之前的 CI build 失效，这一功能非常有用。

这些是基础控制项；高级字段的完整列表记录在 高级 Repository 配置 中。

#安全与访问

• webhook payload 会根据 webhook.secret 进行验证；该值仅存储在集群 Secret 中，不会出现在事件或日志里。
• Git access token（Webhook 模式）或 GitHub App private key（App 模式）同样会存储为 Kubernetes Secret；token 不会出现在 PipelineRun specs 中。
• Repository 是命名空间级资源；标准 Kubernetes RBAC 决定谁可以创建或修改它。授予“读取 repositories”而不授予“创建”权限，可以让用户查看已集成的内容，但不能修改它。
• 向 Git provider 回报状态时始终使用集群侧身份（App 模式下使用 App，Webhook 模式下使用配置的 token）。不会向单个事件发送者委派权限。

#后续步骤

• 快速开始 — 端到端的最小示例。
• 指南 — 按 Git provider 划分的完整配置流程。
• 在 Git 中定义 PipelineRuns — 注解语法和 PipelineRun 布局。
• 常见问题 — 故障排查。