核心概念
本页介绍 PAC 在 Tekton 之上引入的资源、运行时组件以及触发模型。要快速了解整体概览和适用对象映射,请参阅 Introduction。
架构
PAC 在集群中运行三个 controller,并响应 Git provider 传递的事件:
- PAC Webhook 是暴露给 Git provider 的 HTTP 监听器。它会使用共享的 webhook secret 验证每个传入请求,并将已验证的 payload 转发给 controller。任何未通过验证的内容都会在触达 Tekton 之前被丢弃。
- PAC Controller 负责“这个事件应该运行什么”的逻辑。它会查找匹配的
Repository资源,从事件所指向的 ref 中获取.tekton/清单,通过 trigger 注解进行过滤,展开变量,并创建PipelineRuns。 - PAC Watcher 跟踪 PAC 创建的
PipelineRuns,并将其状态回报给 Git provider——根据 provider 的不同,以 GitHub Check Run、commit status 或 comment 的形式返回。
这三个组件都位于 PAC namespace 中(默认:tekton-pipelines)。Tekton Operator 会根据 TektonConfig 派生出 OpenShiftPipelinesAsCode CR,并据此部署这些组件——参见 How the Operator Manages PAC。
Repository 资源
Repository 是你针对每个 Git repository 维护的唯一资源。它将一个 Git URL 绑定到一个 Kubernetes namespace:来自该 URL 的事件会在这个 namespace 中生成 PipelineRuns,而且只会在这个 namespace 中生成。多个 Repository 资源可以指向同一个 Git URL,但必须位于不同的 namespace 中——这种布局通常用于“每个环境一个团队 namespace”。
Repository 不包含任何 pipeline 定义。pipeline 定义保存在 Git repository 本身中,即 .tekton/ 下。删除 Repository 只会停止 PAC 创建新的 PipelineRuns;已经创建的运行会保留不变。
关键 spec 字段
示例(通过 Webhook 的 GitLab):
在 GitHub App mode 下,整个 git_provider 块都会省略。PAC 使用集群级别的 App 凭据进行认证,因此不需要按 repository 配置 token 和 webhook secret。此 mode 不使用自动 webhook 注册,因为 webhook 由 GitHub App 负责投递。
两种集成模式
Git provider 向 PAC 投递事件有两种方式,Repository spec 会随之呈现不同形态。
- GitHub App mode —— 在 GitHub organization 或 user 上一次性安装 GitHub App。App 在 organization 级别拥有 webhook 和凭据。安装范围内的每个 repository 都可以通过最小化的
Repository(仅spec.url)接入。状态通过 GitHub Checks API 报告。仅适用于 GitHub。 - Webhook mode —— 为每个 repository 单独配置 Personal Access Token 和 webhook。
Repository会引用一个包含 token 和 webhook secret 的 KubernetesSecret,并且必须将spec.git_provider.type设置为github或gitlab,以便进行自动 webhook 注册。状态以 commit status 的形式报告。本文档涵盖 GitHub Webhook mode 和 GitLab Webhook mode。
这两种 mode 在同一个 Repository 上是互斥的。各 provider 的端到端流程请参见 Guides。
.tekton/ 目录约定
PAC 会从 Git repository 根目录下的 .tekton/ 目录读取 PipelineRun 清单。该约定如下:
- 会扫描
.tekton/下所有.yaml或.yml文件。每个文件中可以包含多个 PipelineRun,每个 repository 中也可以有多个文件。 - 清单会从事件触发时所在的 ref 读取——pull request 读取源分支,push 读取被推送的分支,tag push 读取 tag 的 ref。
- 每个
PipelineRun都会独立评估。单个事件可能生成零个、一个或多个PipelineRun,具体取决于有多少清单匹配。 - 适用标准的
PipelineRun结构;PAC 只是在其基础上追加 annotations 和变量。Task 可以是内联形式(pipelineSpec),引用集群中已有的Pipeline(pipelineRef),或者在提交时从artifacthub-shim提供的 DevOps Hub catalog 或远程 URL 解析得到。
事件生命周期
下面是一些需要牢记的特性:
- webhook 处的验证步骤是 fail-closed:带有无效签名的事件不会到达 controller、
Repositorycontroller 或集群。 - controller 会在创建任何 Kubernetes 对象之前完成过滤和变量展开,因此不匹配的事件不会生成
PipelineRun,除了一条 log 之外不会留下任何痕迹。 - 状态报告是异步的,并会在
PipelineRun状态发生变化时触发,包括完成以及单个步骤失败(前提是 provider 支持逐步骤报告)。
触发模型
PipelineRun 清单通过 metadata.annotations 上的注解声明它们关心的事件。controller 会根据这些注解对事件过滤清单。
事件类型
注解语法
一对简单的匹配器(on-event + on-target-branch)已经足以覆盖大多数场景。对于复合条件(例如“仅当 PR head 匹配 feature/* 且变更文件包含 api/**”),请改用 CEL expression:
CEL 程序可接收 event、event_title、target_branch、source_branch、body、headers,以及一个带有 all、added、deleted、modified 和 renamed 列表的 files 对象。
完整的注解语法、更多 CEL 示例以及冲突解决规则,请参见 Define PipelineRuns in Git。
变量与解析
在创建 PipelineRun 时,PAC 会根据事件 payload 展开一小组占位符。其值会在创建后固定到 PipelineRun 上,不会重新计算。
PAC 还可以在提交时内联 Task 和 Pipeline 清单——可以是通过路径引用的本地文件、通过短名称引用的 DevOps Hub 资源,或者远程 URL。解析器会在创建 PipelineRun 之前运行,因此生成的对象是自包含的。有关语法和支持的来源,请参见 PAC Resolver。
状态报告
PAC 会通过三种通道将 PipelineRun 状态回报给 Git provider,并会根据 provider 和集成 mode 自动选择:
- GitHub Checks API —— 用于 GitHub App mode。每个
PipelineRun都会显示为一个 Check Run,并在 commit 上附带逐步骤输出以及 “in progress / success / failure” 徽标。 - Commit statuses —— 用于 GitHub Webhook mode 和 GitLab。会针对 commit 以及(在相关情况下)PR / MR 发布一条简短的状态行。
- Comment —— 对于失败场景,会在 PR / MR 中添加一条包含
PipelineRun名称以及集群链接的 comment。具体格式取决于 provider。
状态报告中嵌入的集群侧 URL 可以通过 TektonConfig 中的 custom-console-url-* 设置进行自定义;参见 Manage PAC Component。注意,custom-console-url-namespace-vars 属于 options.configMaps,而不是 settings——Where to Put Each Setting 解释了原因。
并发与取消
默认情况下,每个匹配事件都会立即创建其 PipelineRun。有两个设置会影响这一行为:
Repository.spec.concurrency_limit限制该 repository 中可并行运行的PipelineRuns 数量。超出的运行会排队,并在较早的运行完成后启动。PipelineRun上的pipelinesascode.tekton.dev/cancel-in-progress注解会指示 PAC:在启动新的运行之前,取消任何与同一事件组(例如同一个 PR)匹配的旧运行——当对 PR 进行新的 push 会使之前的 CI build 失效时,这尤其有用。
这些是基础控制项;完整的高级字段请参见 Advanced Repository Configuration。
安全与访问
- webhook payload 会使用
webhook.secret进行验证;该值仅存在于集群Secret中,不会出现在事件或 log 中。 - Git access token(Webhook mode)或 GitHub App private key(App mode)同样存储为 Kubernetes
Secret;token 不会出现在PipelineRunspec 中。 Repository是 namespaced 资源;标准 Kubernetes RBAC 决定谁可以创建或修改它。只授予“read repositories”而不授予“create”,可让用户查看已集成内容而不更改它。- 向 Git provider 回传状态时始终使用集群侧身份(App mode 下使用 App,Webhook mode 下使用已配置的 token)。不会将单个事件发送者的权限委派出去。
下一步
- Quick Start — 端到端最小示例。
- Guides — 按 Git provider 展开的完整配置流程。
- Define PipelineRuns in Git — 注解语法和
PipelineRun布局。 - Common Issues — 故障排查。