核心概念

本页介绍 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 字段

字段作用
spec.urlGit repository URL。PAC 使用它来匹配传入事件。
spec.git_provider.typeprovider 类型,例如 github 或 gitlab。WebHook 模式和自动 webhook 注册需要该字段。
spec.git_provider.urlprovider API 基础 URL。自托管 GitLab 必填;其他场景可选。
spec.git_provider.secret指向 Secret 的引用,其中保存了 provider.token 下的 Git 访问令牌。
spec.git_provider.webhook_secret指向 Secret 的引用,其中保存了 webhook.secret 下的 webhook 签名 secret。
spec.concurrency_limit可选项,限制来自该 repository、允许并发执行的 PipelineRuns 数量上限。
spec.paramsrepository 作用域参数;该 repository 中的任何 PipelineRun 都可以使用 {{ name }} 占位符读取这些参数。
spec.settings授权策略和 provider 特定选项,例如允许哪些用户通过 comment 触发。

示例(通过 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。由于 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 会引用一个 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 清单。约定如下:

  • 会扫描 .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、Repository controller 或集群。
  • controller 会在创建任何 Kubernetes 对象之前执行筛选和变量展开,因此不匹配的事件不会生成 PipelineRun,除了一条日志外不会留下任何痕迹。
  • 状态报告是异步的,并会在 PipelineRun 状态变化时触发,包括完成以及单个步骤失败(前提是 provider 支持按步骤报告)。

触发模型

PipelineRun 清单通过 metadata.annotations 上的注解声明它们关心的事件。controller 会使用这些注解来筛选与事件匹配的清单。

事件类型

事件含义备注
push有 commit 被推送到某个分支当 ref 是 tag 时,也包括 tag push
pull_request打开、更新或同步了一个 pull request / merge request清单从 PR 源分支读取
pull_request_labeled有 label 被应用到 pull request适合基于 reviewer label 控制运行
pull_request_closedpull request 被关闭(无论是否已合并)
comment在 PR / commit 上发布了 comment通常与 on-comment 结合,用于自定义命令
incoming外部 incoming webhook 触发了运行参见 Incoming Webhooks

注解语法

注解作用
pipelinesascode.tekton.dev/on-event该 run 适用的事件类型,例如 [push, pull_request]。
pipelinesascode.tekton.dev/on-target-branch目标分支过滤器;支持普通名称、完整 ref 和 glob 模式,例如 [refs/heads/main]、[refs/tags/*]。
pipelinesascode.tekton.dev/on-cel-expressionCEL 表达式。设置后,它会替代 on-event 和 on-target-branch。
pipelinesascode.tekton.dev/on-comment与 PR / MR comment 匹配的正则表达式——这是 /retest 以及类似命令的基础。
pipelinesascode.tekton.dev/on-path-change仅在变更文件匹配某个 glob 时运行,例如 [backend/***]。
pipelinesascode.tekton.dev/on-path-change-ignore当变更文件匹配某个 glob 时跳过——适用于忽略仅文档变更。

一对简单的匹配器(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 中;它们不会重新计算。

变量值
{{ repo_url }}Git provider 上的 repository URL
{{ revision }}事件对应的 commit SHA
{{ source_branch }}事件发起所在的分支(PR head)
{{ target_branch }}事件目标分支(PR base)
{{ repo_owner }}, {{ repo_name }}repository 的所有者和名称
{{ sender }}事件发送者的用户名或账户 ID
{{ pull_request_number }}PR / MR 编号,适用于 pull request 事件
{{ git_auth_secret }}自动创建的 Secret 名称,其中包含该 run 的 clone 凭据

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 中;令牌不会出现在 PipelineRun spec 里。
  • Repository 是命名空间级资源;标准 Kubernetes RBAC 决定谁可以创建或修改它。授予“读取 repository”但不授予“创建”权限,可以让用户查看已集成内容而不修改它。
  • 向 Git provider 回报状态时始终使用集群侧身份(App 模式下使用 App,Webhook 模式下使用已配置的 token)。不会为单个事件发送者委派权限。

后续步骤