核心概念

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

字段作用
spec.urlGit repository URL。PAC 会将传入事件与此值匹配。
spec.git_provider.typeprovider 类型,例如 github 或 gitlab。Webhook mode 和自动 webhook 注册都需要此字段。
spec.git_provider.urlprovider API 基础 URL。自托管 GitLab 必填;其他场景可选。
spec.git_provider.secret指向存放 provider.token 下 Git access token 的 Secret 的引用。
spec.git_provider.webhook_secret指向存放 webhook.secret 下 webhook signing secret 的 Secret 的引用。
spec.concurrency_limit可选项,用于限制该 repository 中可并发执行的 PipelineRuns 数量。
spec.paramsrepository 级参数,任何来自此 repo 的 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 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 的 Kubernetes Secret,并且必须将 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、Repository controller 或集群。
  • controller 会在创建任何 Kubernetes 对象之前完成过滤和变量展开,因此不匹配的事件不会生成 PipelineRun,除了一条 log 之外不会留下任何痕迹。
  • 状态报告是异步的,并会在 PipelineRun 状态发生变化时触发,包括完成以及单个步骤失败(前提是 provider 支持逐步骤报告)。

触发模型

PipelineRun 清单通过 metadata.annotations 上的注解声明它们关心的事件。controller 会根据这些注解对事件过滤清单。

事件类型

事件含义备注
push有 commit 被推送到某个分支当 ref 是 tag 时也包括 tag push
pull_requestpull 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适用的事件类型,例如 [push, pull_request]。
pipelinesascode.tekton.dev/on-target-branch目标分支过滤器;支持普通名称、完整 ref 和 glob 模式,例如 [refs/heads/main]、[refs/tags/*]。
pipelinesascode.tekton.dev/on-cel-expressionCEL expression。设置后会替代 on-event 和 on-target-branch。
pipelinesascode.tekton.dev/on-comment与 PR / MR comment 匹配的 regular expression——是 /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 expression:

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 示例以及冲突解决规则,请参见 Define PipelineRuns in Git。

变量与解析

在创建 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 }}事件发送者的用户名或 account ID
{{ pull_request_number }}PR / MR 编号,适用于 pull request 事件
{{ git_auth_secret }}自动创建的、包含该运行 clone 凭据的 Secret 名称

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 不会出现在 PipelineRun spec 中。
  • Repository 是 namespaced 资源;标准 Kubernetes RBAC 决定谁可以创建或修改它。只授予“read repositories”而不授予“create”,可让用户查看已集成内容而不更改它。
  • 向 Git provider 回传状态时始终使用集群侧身份(App mode 下使用 App,Webhook mode 下使用已配置的 token)。不会将单个事件发送者的权限委派出去。

下一步