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