核心概念
本页介绍 PAC 在 Tekton 之上引入的资源、运行时组件和触发模型。如需快速概览和受众映射,请参见 简介。
架构
PAC 在集群中运行三个 controller,并对 Git provider 传递的事件做出响应:
- PAC Webhook 是暴露给 Git provider 的 HTTP 监听器。它会使用共享的 webhook secret 验证每个传入请求,并将已验证的 payload 转发给 controller。任何验证失败的内容都会在触达 Tekton 之前被丢弃。
- PAC Controller 负责处理“在此事件上应该运行什么”的逻辑。它会查找匹配的
Repository资源,从事件所引用的 ref 中获取.tekton/清单,通过触发注解进行筛选,展开变量,并创建PipelineRuns。 - PAC Watcher 跟踪 PAC 创建的
PipelineRuns,并将其状态回报给 Git provider——根据 provider 的不同,可以是 GitHub Check Run、commit status 或 comment。
这三个组件都位于 PAC namespace 中(默认值:tekton-pipelines),并由 Tekton Operator 基于 OpenShiftPipelinesAsCode CR 进行部署。
Repository 资源
Repository 是您为每个 Git repository 维护的唯一资源。它将一个 Git URL 绑定到一个 Kubernetes namespace:来自该 URL 的事件会在这个 namespace 中生成 PipelineRuns,而且只会在这个 namespace 中生成。多个 Repository 资源只能在不同 namespace 中指向同一个 Git URL——这通常适用于“每个环境一个 team namespace”的布局。
Repository 不包含任何 pipeline 定义。pipeline 定义保存在 Git repository 本身的 .tekton/ 目录下。删除 Repository 只会停止 PAC 创建新的 PipelineRuns;已经创建的运行会保留不变。
关键 spec 字段
示例(通过 Webhook 的 GitLab):
在 GitHub App 模式下,整个 git_provider 块会被省略。PAC 使用集群级别的 App 凭据进行身份验证,因此不需要按 repository 配置 token 和 webhook secret。由于 GitHub App 负责 webhook 投递,因此该模式不会使用自动 webhook 注册。
两种集成模式
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会引用一个 KubernetesSecret,其中包含 token 和 webhook secret,并且必须将spec.git_provider.type设置为github或gitlab,以便进行自动 webhook 注册。状态会以 commit status 的形式报告。本文档涵盖 GitHub Webhook 模式和 GitLab Webhook 模式。
在同一个 Repository 上,这两种模式互斥。每个 provider 的端到端流程请参见 指南。
.tekton/ 目录约定
PAC 会从 Git repository 根目录下的 .tekton/ 目录读取 PipelineRun 清单。约定如下:
- 会扫描
.tekton/下所有.yaml或.yml文件。每个文件中可以有多个 PipelineRun,每个 repository 也可以有多个文件。 - 清单会从触发事件所在的 ref 中读取——pull request 读取源分支,push 读取被推送的分支,tag push 读取 tag 的 ref。
- 每个
PipelineRun都会独立评估。一个事件可以根据匹配到的清单数量,生成零个、一个或多个PipelineRuns。 - 适用标准
PipelineRun结构;PAC 只是在其上添加注解和变量。Task 可以是内联的(pipelineSpec)、引用集群中已有的Pipeline(pipelineRef),或者在提交时从 Tekton Hub 或远程 URL 解析。
事件生命周期
有几个值得注意的特性:
- webhook 处的验证步骤采用 fail-closed 策略:签名无效的事件不会到达 controller、
Repositorycontroller 或集群。 - controller 会在创建任何 Kubernetes 对象之前执行筛选和变量展开,因此不匹配的事件不会生成
PipelineRun,除了一条日志外不会留下任何痕迹。 - 状态报告是异步的,并会在
PipelineRun状态变化时触发,包括完成以及单个步骤失败(前提是 provider 支持按步骤报告)。
触发模型
PipelineRun 清单通过 metadata.annotations 上的注解声明它们关心的事件。controller 会使用这些注解来筛选与事件匹配的清单。
事件类型
注解语法
一对简单的匹配器(on-event + on-target-branch)足以应对大多数场景。对于复合条件(例如“仅当 PR head 匹配 feature/* 且 变更文件包含 api/** 时”),请改用 CEL 表达式:
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 清单——包括通过路径引用的本地文件、通过短名称引用的 Tekton Hub 资源,或远程 URL。解析器会在创建 PipelineRun 之前运行,因此生成的对象是自包含的。有关语法和受支持来源,请参见 PAC Resolver。
状态报告
PAC 会通过三种通道将 PipelineRun 状态回报给 Git provider,并会根据 provider 和集成模式自动选择:
- GitHub Checks API — 在 GitHub App 模式下使用。每个
PipelineRun都会显示为一个 Check Run,附带按步骤输出,并在 commit 上显示“进行中 / 成功 / 失败”徽标。 - Commit statuses — 在 GitHub Webhook 模式和 GitLab 中使用。系统会针对 commit 以及(如适用)PR / MR 发布一条简短状态。
- Comment — 对于失败情况,会在 PR / MR 上添加一条 comment,其中包含
PipelineRun名称和集群链接。具体格式取决于 provider。
这些状态报告中嵌入的集群侧 URL 可通过 OpenShiftPipelinesAsCode 中的 custom-console-url-* 设置进行自定义;请参见 管理 PAC 组件。
并发与取消
默认情况下,每个匹配事件都会立即创建其 PipelineRun。以下两个设置决定了这种行为:
Repository.spec.concurrency_limit限制来自该 repository、可并行运行的PipelineRuns 数量。超出部分会排队,并在较早的运行完成后启动。PipelineRun上的pipelinesascode.tekton.dev/cancel-in-progress注解会指示 PAC:在启动新的 run 之前,取消与同一事件组(例如同一个 PR)匹配的任何旧 run——当 PR 有新的 push 时,这对于让之前的 CI 构建失效非常有用。
以上是基础控制项;高级字段的完整集合请参见 高级 Repository 配置。
安全与访问
- webhook payload 会根据
webhook.secret进行验证;该值仅保存在集群Secret中,不会出现在事件或日志里。 - Git 访问令牌(Webhook 模式)或 GitHub App 私钥(App 模式)同样存储在 Kubernetes
Secret中;令牌不会出现在PipelineRunspec 里。 Repository是命名空间级资源;标准 Kubernetes RBAC 决定谁可以创建或修改它。授予“读取 repository”但不授予“创建”权限,可以让用户查看已集成内容而不修改它。- 向 Git provider 回报状态时始终使用集群侧身份(App 模式下使用 App,Webhook 模式下使用已配置的 token)。不会为单个事件发送者委派权限。
后续步骤
- 快速开始 — 端到端最小示例。
- 指南 — 按 Git provider 划分的完整配置流程。
- 在 Git 中定义 PipelineRuns — 注解语法和
PipelineRun布局。 - 常见问题 — 故障排查。