在 Git 中定义 PipelineRuns
本指南面向在 Git 仓库中定义 PAC PipelineRun 清单的普通用户。
PAC 从 .tekton/ 读取 Tekton PipelineRun 清单,将其与 Git 事件进行匹配,并在 Repository CR 的命名空间中创建匹配的 PipelineRun。
目录
Pipeline 文件位置选择 Pipeline 定义场景使用pipelineSpec 内联定义 Pipeline使用 pipelineRef 引用 Pipeline在 Git 中定义 Pipeline在集群中定义 Pipeline触发事件匹配 Pull Request 事件匹配 Push 事件匹配自定义评论匹配 Pull Request 标签分支规范分支和路径过滤高级事件匹配正在进行的取消参数化提交和 URLTask 解析故障排除将仓库纳入管理的约定三种触发模式为 merge request 和主分支使用一个定义引用共享 Pipeline 模板纳入管理自检后续步骤Pipeline 文件位置
PAC 处理 .tekton/ 下的所有 .yaml 和 .yml 文件:
每个 PipelineRun 都会独立进行评估。如果多个文件匹配同一事件,PAC 会创建多个 PipelineRuns。
选择 Pipeline 定义场景
选择 PipelineRun 定义待运行工作的方式:使用 pipelineSpec 内联定义,或通过 pipelineRef 引用可复用的 Pipeline。
使用 pipelineSpec 内联定义 Pipeline
当 Pipeline 逻辑应直接存放在与触发器定义相同的 Git 文件中时,请使用 pipelineSpec:
注意:本页面中的示例使用公共 alpine:latest 镜像。请将其替换为集群可以拉取的镜像,例如来自内部 registry 的镜像。
注意:使用内联 pipelineSpec 或 taskSpec 的示例,以及 PAC 使用默认 remote-tasks: "true" 嵌入的 Pipelines 和 Tasks(请参阅 在 Git 中定义 Pipeline 和 Task 解析),假定集群设置 disable-inline-spec 为空。如果其中包含 pipelinerun,Tekton webhook 会拒绝带有内联 pipelineSpec 的 PipelineRun;请参阅 使用 Kyverno 约束 Tekton Pipeline 执行 第 1 节中的警告。
使用 pipelineRef 引用 Pipeline
当 PipelineRun 应复用 Pipeline 定义时,请使用 pipelineRef。
在 Git 中定义 Pipeline
使用默认的 remote-tasks: "true" 时,普通的 pipelineRef.name 应引用 PAC 可以从 Git 解析的 Pipeline。
PAC 首先检查 pipelinesascode.tekton.dev/pipeline 注解,然后检查 .tekton/ 下及其子目录中的 Pipeline 文件。
常见布局:
pipeline.yaml:
pipelinerun.yaml:
对于其他 Pipeline 来源,请使用 pipelinesascode.tekton.dev/pipeline。
请参阅 PAC Resolver 和 PAC Pipeline 解析文档。
在集群中定义 Pipeline
如果 Pipeline 已由集群管理,例如由平台 Pipeline 产品管理,请使用以下方法之一。
保留 remote-tasks: "true",并使用 Tekton 集群 resolver 引用命名空间范围内的 Pipeline:
除非集群 resolver 配置了默认命名空间,否则请保留 namespace 参数。如果此参数和 resolver 默认命名空间都为空,解析将失败。
另一种方法是由管理员在 PAC 组件配置中设置 remote-tasks: "false"。
在此模式下,普通的 pipelineRef.name 可以引用与生成的 PipelineRun 位于同一命名空间中的 Pipeline:
PAC 不会在此模式下内联或解析 Pipeline。PAC 创建 PipelineRun 后,Tekton 会解析该引用,因此目标命名空间中必须已经存在该 Pipeline。
触发事件
选择 pipelineSpec 或 pipelineRef 后,添加 PAC 注解,以控制哪些 Git 事件会触发 PipelineRun。
匹配 Pull Request 事件
匹配 Push 事件
匹配自定义评论
使用 on-comment 设置特定于仓库的 pull request 或 merge request 命令。该值是一个正则表达式,用于匹配新评论;PAC 会先删除评论开头和结尾的空格及换行符:
由于此示例还设置了 on-event 和 on-target-branch,因此每次对 main 执行 pull request 或 merge request 的创建和更新操作时,PipelineRun 也会运行,而不仅仅是在出现 /deploy-preview 评论时运行。
on-comment 是技术预览功能。如果希望使用 PAC 的原生命令行为,而不是特定于仓库的触发器,请使用内置的 GitOps 命令,例如 /test、/retest 和 /cancel。
匹配 Pull Request 标签
当 PipelineRun 仅应针对具有匹配标签的 pull request 或 merge request 运行时,请使用 on-label:
on-label 是技术预览功能。它仍依赖于 on-event 和 on-target-branch。GitHub、Gitea 和 GitLab 仓库支持此功能,但 Bitbucket 仓库不支持。
分支规范
on-target-branch 接受完整 ref、分支名称、标签、glob 和以逗号分隔的值。
分支和路径过滤
使用分支注解进行简单过滤:
路径变更注解属于技术预览功能。如果设置了 on-cel-expression,PAC 会忽略 on-path-change 和 on-path-change-ignore。
如果同一事件还更改了 on-path-change-ignore 路径下的文件,则带有路径过滤器的 PipelineRun 不会启动,即使其他变更的文件与 on-path-change 匹配。
在 GitLab 上,PAC 通过 merge request diffs API(GET /projects/:id/merge_requests/:iid/diffs)读取 merge request 中发生变更的文件。如果 GitLab 实例不提供此 API(例如,GitLab 14.0.12 对此返回 404 Not Found),PAC 会为每个 merge request 事件和 merge request 评论记录 error getting changed files: 404 Not Found,带有路径过滤器的 PipelineRun 永远不会针对 merge request 启动。不带路径过滤器的运行仍会创建,push 事件上的路径过滤器不受影响。
高级事件匹配
对于复杂条件,请使用 pipelinesascode.tekton.dev/on-cel-expression。设置 CEL 后,PAC 会使用 CEL 表达式,并忽略 on-target-branch、on-event、on-label、on-path-change 和 on-path-change-ignore。
常用的 CEL 字段包括 event、event_title、target_branch、source_branch、target_url、source_url、files.all、files.added、files.deleted、files.modified、files.renamed、body 和 headers。
正在进行的取消
使用 pipelinesascode.tekton.dev/cancel-in-progress: "true",在同一 PipelineRun 的新运行启动时取消较早的运行。新运行启动时,PAC 只会取消同一命名空间中尚未完成、属于同一仓库且在 .tekton/ 中具有相同 PipelineRun 名称的运行:对于 pull request 事件,只取消同一 pull request 的运行;对于 push 事件,只取消源分支为被推送分支的运行,因此推送到其他分支不会停止这些运行。仅当 Repository 没有 concurrency_limit 时,新运行才能执行此取消操作;该参数可以直接设置在其上,也可以从全局 Repository继承。设置了限制时,新运行不会取消较早的运行,PAC 会在 Repository 上记录事件 error cancelling in progress pipelineRuns: cancel in progress is not supported with concurrency limit(使用 kubectl describe repository <name> -n <namespace> 查看)。
关闭 pull request 或 merge request 也会取消 Repository 命名空间中尚未完成且具有 cancel-in-progress: "true" 的运行,这些运行由打开、重新打开或更新 pull request 或 merge request、对其执行内置 GitOps 命令,或对其添加 on-comment 评论而启动;无论其 PipelineRun 名称是什么,即使 Repository 具有 concurrency_limit,也会取消。在 GitLab 上,合并 merge request 不会取消这些运行。由 pull request 或 merge request 的标签变更启动的运行(其 pipelinesascode.tekton.dev/event-type 标签为 pull_request_labeled)不会因关闭 pull request 或 merge request 而取消。cancel-in-progress 属于技术预览功能。
参数化提交和 URL
PAC 在创建 PipelineRun 之前,会替换 {{ variable_name }} 格式的动态变量。$(params.name) 等 Tekton 参数由 Tekton 在后续处理。
示例:
PAC 会为每个事件将 {{ git_auth_secret }} 填充为生成的 Secret 名称。当 PAC 设置 secret-auto-create 为 "true"(默认值)时,PAC 会使用 Repository 所用 Git provider token 为此次运行创建该 Secret(使用 GitHub App 时,为 GitHub App installation token)。使用 "false" 时,名称仍会被填充,但不存在具有该名称的 Secret。
Task 解析
PAC 可以嵌入由 PAC 注解引用的 Task,也可以直接使用 Tekton resolver 语法。
PAC 仅在使用默认 remote-tasks: "true" 时才会嵌入 pipelinesascode.tekton.dev/task 中指定名称的 Task。使用 remote-tasks: "false" 时,PAC 会忽略 Task 注解,而 Tekton 会在 PipelineRun 所在的命名空间中查找名为 git-clone 的 Task。
有关支持的 Task 和 Pipeline 源,请参见 PAC Resolver。
故障排除
以下是一些有用的检查方法。PAC 会将某些原因作为 Repository 上的事件记录下来,例如,当 /test 指定了不在 .tekton/ 中的 PipelineRun 时,会记录 cannot find the targeted pipelinerun <pipelinerun> in this repository;kubectl describe repository 会在 Repository 命名空间中显示这些事件。事件只会保留有限时间,因此请在事件发生后尽快检查。与任何 PipelineRun 都不匹配的事件不会记录在 Repository 上;其原因会记录在 PAC controller 日志中,而读取该日志需要对 PAC 命名空间中 Pod 日志的读取权限,通常需要集群管理员权限。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会输出最后 10 行,因此,以下最后一条命令会读取最近 10 分钟的所有行;如果事件发生时间更早,请增大 --since:
将仓库纳入管理的约定
以下约定适用于平台团队将许多仓库纳入共享 Pipeline 模板的场景。这些约定缩小了本页所述的选项范围;维护自身 Pipeline 的仓库可以继续使用 pipelineSpec 或 Git 中定义的 Pipeline。有关纳入管理的具体步骤,请参阅配置 GitLab 仓库或配置 GitHub 仓库。
三种触发模式
路径变更注解和 on-comment 目前属于 Technology Preview。对于 /deploy-preview 等特定于仓库的操作,请保留 on-comment;对于运行和重新运行 Pipeline,请使用触发 PAC Pipeline中所述的内置命令。如果设置了 on-cel-expression,PAC 会忽略 on-event、on-target-branch 以及路径过滤器。在 GitLab 上,merge request 事件的路径过滤器需要 merge request diffs API;请参阅分支和路径过滤。
为 merge request 和主分支使用一个定义
对于 pull request 或 merge request 以及推送到主分支,请使用一个 PipelineRun 定义,而不是使用两个会逐渐偏离的副本。将 on-event 设置为这两个事件,并将 on-target-branch 设置为该分支:对于 pull_request,PAC 匹配目标分支;对于 push,PAC 匹配被推送的分支。如果共享 Pipeline 必须仅针对主分支运行发布等仅限 push 的步骤,请将 {{ source_branch }}、{{ source_url }} 和 {{ repo_url }} 作为参数传入,并且仅当源分支是主分支且源仓库就是该仓库本身时运行这些步骤。不要以 {{ event_type }} 为判断依据:在 GitLab 上,merge request 事件会将其呈现为 Merge Request,而 /test 和 /retest 评论会将其呈现为 pull_request,即使提交评论重新运行的是主分支也是如此。
在共享 Pipeline 中声明参数,并使用两个 when 表达式保护仅限 push 的 Task;只有两个表达式都为 true 时,Task 才会运行:
引用共享 Pipeline 模板
.tekton/ 下的 PipelineRun 通过 pipelineRef.resolver 引用共享 Pipeline 模板:对于集群命名空间中管理的 Pipeline,使用 cluster(请参阅使用 pipelineRef 引用 Pipeline);对于版本化目录中的 Pipeline,使用 hub;对于存储在模板仓库中的 Pipeline,使用 git(请参阅Resolvers)。要选择模板版本,请为 hub resolver 设置 version 参数,或为 git resolver 设置 revision 参数。对于 git resolver,revision 可以是分支、标签或提交(请参阅Resolvers);只有提交 SHA 会固定内容,因此迁移到新的模板版本会改变 .tekton/。分支或可移动的标签无需更改 .tekton/ 即可解析到新内容。对于 hub resolver,version 指定已发布的目录版本;发布后其内容是否可以更改取决于目录的维护方式,因此在依赖其作为固定版本之前,请向目录管理员确认。cluster resolver 接受 kind、name 和 namespace(以及可选的 cache 模式),且没有版本参数。
hub 示例还设置了 catalog,即要读取的目录名称。内置 Pipeline 从 catalog-pipelines 提供,内置 Task 从 catalog 提供(请参阅Resolvers);使用 catalog: catalog 的旧 Pipeline 引用仍会通过兼容性别名解析,但新的 Pipeline 引用应使用 catalog-pipelines。如果集群中配置的目录名称不同,请将其替换为该名称。在每个 hub 引用中保留 catalog、kind、name 和 version:在实施使用 Kyverno 约束 Tekton Pipeline 执行中 require-hub-reference-shape 规则的命名空间中,如果 PipelineRun 的 hub 引用将其中任何一个留空,或将 kind 设置为 pipeline 以外的值,则会被拒绝。该规则还会拒绝 resolver 不是 hub 的 PipelineRun,因此在此类命名空间中,cluster 和 git 形式都会被拒绝。
不要对平台模板使用不带其他配置的 pipelineRef.name。使用默认 remote-tasks: "true" 时,PAC 会从 pipelinesascode.tekton.dev/pipeline 注解或 .tekton/ 中解析此类引用,并将解析后的 Pipeline 作为内联 pipelineSpec 嵌入生成的 PipelineRun 中;仅存在于集群中的 Pipeline 将无法找到。resolver 形式由 Tekton 而非 PAC 处理,因此生成的 PipelineRun 会保留对模板的引用。这也使运行与拒绝内联 pipelineSpec 的准入策略保持兼容,例如使用 Kyverno 约束 Tekton Pipeline 执行中的 deny-pipelinerun-inline-pipelinespec 规则;该指南中的 resolver 规则还要求使用 hub resolver。
纳入管理自检
将仓库纳入管理后,请确认每一项。标记为Webhook 模式的项目适用于通过令牌和 webhook 连接的仓库(GitLab,或处于 Webhook 模式的 GitHub);标记为 GitHub App 模式的项目适用于通过 GitHub App 连接的 GitHub 仓库,这类仓库不需要每个仓库单独配置 Secret 或 webhook(请参阅配置 GitHub 仓库)。
- 项目命名空间中存在
RepositoryCR,且其spec.url与仓库匹配。 - Webhook 模式:
spec.git_provider.secret和spec.git_provider.webhook_secret引用同一命名空间中包含provider.token和webhook.secret的 Secret;或者 Repository 包含不带这两个字段的git_provider块,并从全局 Repository CR 继承这两个字段,而该 CR 的 Secret 位于 PAC 命名空间中;请参阅为 PAC 创建 Git Secret和创建全局 Repository CR。 - Webhook 模式:webhook 处于活动状态:
Repository上的pac.tekton.alauda.io/webhook-registration-status注解为Registered,或者 webhook 是通过仓库指南中的手动备用方式添加的。如果状态为Failed,请读取pac.tekton.alauda.io/webhook-registration-reason注解:FailedRepository 仍可能拥有在早期注册中创建的活动 webhook。 - GitHub App 模式:仓库已包含在 GitHub App 安装中,并且 PAC 命名空间中的
pipelines-as-code-secretSecret 保存了 App ID、私钥和 webhook Secret;请参阅集成模式 1:GitHub App。 -
.tekton/下的每个PipelineRun都具有与仓库所使用的事件和分支匹配的on-event和on-target-branch值。 - 每个
spec.pipelineRef都使用resolver形式,而不是不带其他配置的name,并在 resolver 支持时选择模板版本:对于hub,使用version;对于git,使用作为提交 SHA 的revision(分支或可移动标签不会固定内容)。 -
.tekton/下的每个PipelineRun都会在其触发模式的第一个事件上运行(请参阅三种触发模式):事件驱动模式在匹配的 push 或 pull request 或 merge request 更新上运行;评论驱动模式在/test <pipelinerun-name> branch:<branch>评论上运行;带路径过滤的模式在匹配的事件修改了过滤路径下的文件且未修改on-path-change-ignore路径下的文件时运行(如果同一事件还修改了被忽略的文件,则不会启动运行)。kubectl get pipelineruns -n <namespace> -l pipelinesascode.tekton.dev/repository=<repository-name>会列出该运行,Git 提供商会显示其结果:Webhook 模式下显示提交状态,GitHub App 模式下显示提交上的 Check Run。 - merge request 上的
/test <pipelinerun-name> branch:<source-branch>评论会启动该 merge request 源分支的新运行。
后续步骤
- PAC Resolver - 远程 Task 和 Pipeline 源
- PAC 文档 - Pipelines as Code 文档
- 触发 PAC Pipeline - 自动事件和评论命令
- 指南 - 仓库设置指南
- 常见问题 - 故障排除指南