触发 PAC Pipeline
本页面介绍在连接仓库后,PAC 如何启动 PipelineRun。要定义 PAC 选择的 .tekton/ 文件,请参阅在 Git 中定义 PipelineRun。
PAC 通过三种方式触发 Pipeline:
- 自动事件触发器:Git provider 发送 webhook 事件,PAC 将这些事件与
PipelineRun文件上的注解进行匹配。 - 评论命令触发器:授权用户使用 PAC 命令发表评论,例如
/test、/retest或/cancel。 - 传入 webhook 触发器:外部系统向 PAC controller 的
/incomingendpoint 发送 HTTP POST 请求,以触发具有自身incoming规则的Repository。本页面不介绍这些内容;请参阅传入 Webhook。
自动事件触发器
自动触发器由 .tekton/ 下每个 PipelineRun 中的注解控制。PAC 从触发事件的 Git ref 读取 PipelineRun 定义,匹配注解,替换 PAC 变量,并在 Repository namespace 中创建匹配的 PipelineRun。如果使用 pipelinerun_provenance: default_branch 而不是默认的 source,PAC 会从名称为仓库默认分支的分支(例如 main)读取定义,无论 pull request 或 merge request 来自哪个分支;请参阅源分支配置。
下表说明应使用哪种事件源。有关确切的注解语法和示例,请参阅触发事件。PAC event 列显示 on-event 注解匹配的值;自定义评论则由 on-comment 注解进行匹配。{{ event_type }} 变量可以为同一事件保存不同的值,例如 GitLab 上的 Merge Request 或 pull_request_labeled;请参阅参数化提交和 URL。
对于特定于仓库的命令(例如 /deploy-preview),请使用自定义评论触发器。当需要 PAC 原生的重新运行、测试、取消或审批行为时,请使用下面的内置 PAC 命令。
有关更多匹配选项,请参阅 Pipelines as Code 事件匹配文档。
评论命令触发器
PAC 还会识别评论中的内置 GitOps 命令。当您希望运行、重新运行、批准或取消 Pipeline,而无需再次推送提交时,这些命令非常有用。
Pull Request 和 Merge Request 上的命令
在已打开的 PR 或 MR 上使用这些命令。默认命令前缀显示为 /。在 GitHub 上,将 settings.gitops_command_prefix 设置为 <prefix> 的 Repository 仅接受 /<prefix> test、/<prefix> retest 等形式的内置命令;GitLab 无论该设置如何,均使用 /:
<pipelinerun> 是 .tekton/ 文件中的 metadata.name 或 metadata.generateName 值,而不是生成的运行时名称。例如,如果文件中包含 generateName: sv-event-pr-,请使用:
提交评论上的命令
GitLab 以及使用 GitHub App 的 GitHub 支持在推送分支提交的评论上使用 /test、/retest 和 /cancel。在 GitHub Webhook 模式下,PAC 会拒绝每条提交评论,并且不会创建 PipelineRun;请改为在 pull request 上发表评论(请参阅Provider 说明)。/ok-to-test 用于 PR/MR 授权,不适用于推送的提交。
当您在提交上发表评论时,PAC 必须知道要使用哪个分支或标签上下文。如果未指定,PAC 会使用仓库默认分支。被评论的提交必须是该分支的 HEAD 提交,或者是该标签指向的提交。
当提交属于非默认分支时,请使用 branch:<branch>:
当命令应在标签上下文中运行时,请使用 tag:<tag>。GitHub 配合 GitHub App 时(不适用于 GitHub Webhook 模式)以及 GitLab 均支持此功能。请将评论添加到标签指向的提交上。在 GitLab 上,对其他提交的评论不会创建 PipelineRun,原因只会显示在 PAC controller 日志中,而不会作为 Repository 上的事件显示;读取该日志需要对 PAC namespace 中 Pod 日志的读取权限,通常需要集群管理员权限。在 GitLab 的标签上下文中,{{ source_branch }} 和 {{ target_branch }} 为 refs/tags/<tag>,而 {{ git_tag }} 为 <tag>:
/retest 和 /cancel 也接受相同的分支参数。在 GitHub 标签评论中,两者也都接受标签参数。在 GitLab 上,/retest 以与 /test 相同的方式接受标签参数:
在命令中传递参数
在命令中传递参数属于 Technology Preview。内置命令可以包含 key=value 参数。PAC 会从评论中解析这些参数,并可使用它们覆盖 Repository.spec.params 中定义的自定义参数或受支持的标准变量:
只有已为 Repository 定义或 PAC 能够识别的参数才会应用。任意键都会被忽略。
Provider 说明
有关命令的更多详细信息,请参阅 Pipelines as Code GitOps 命令文档。
验证触发器
发送事件或评论后,检查定义了 Repository CR 的命名空间中的 PipelineRun:
如果未创建任何 PipelineRun,请先检查事件注释。PAC 会将某些原因记录为 Repository 上的事件,例如,当 /test 指定的 PipelineRun 不在 .tekton/ 中时,会记录 cannot find the targeted pipelinerun <pipelinerun> in this repository。请在 Repository 命名空间中读取这些事件;事件只会保留有限时间,因此请在事件发生后尽快检查:
与任何 PipelineRun 都不匹配的事件,以及 PAC 拒绝的提交评论,不会记录在 Repository 中;其原因会记录在 PAC 控制器日志中。读取该日志需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常需要集群管理员权限。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会输出最后 10 行,因此该命令会读取最近 10 分钟内的每一行;如果事件发生时间更早,请增大 --since:
常见检查项:
平台约定
启用时机。当多个仓库共用一个 PAC 安装实例,且贡献者需要在这些仓库之间切换时,采用此约定。让每个仓库使用相同的命令后,一套说明即可覆盖所有项目,无需为每个仓库分别制定重试或分支触发操作步骤。
建议值。将 /test <pipelinerun-name> branch:<branch> 用作唯一的命令形式,同时用于拉取请求或合并请求评论以及提交评论。branch: 的行为取决于评论发布的位置。在提交评论中,它用于选择要运行的分支,并且被评论的提交必须是该分支的 HEAD;请显式指定分支,而不要依赖仓库的默认分支(请参阅提交评论中的命令)。在拉取请求或合并请求评论中,PAC 始终运行该拉取请求或合并请求的源(head)分支,并忽略 branch:,因此请在此处填写源分支,以保持命令形式一致。只有在提交评论中才能运行其他分支;而在 GitHub 上,这仅适用于 GitHub App:在 GitHub Webhook 模式下,PAC 会拒绝每条提交评论,因此贡献者应在那里评论拉取请求。Provider 说明表格解释了为什么所有位置都使用一种内置形式:在 GitLab 上,提交评论仅接受 /test、/retest 和 /cancel,因此自定义的 on-comment 命令只能在开放的合并请求评论中使用;在使用 GitHub App 的 GitHub 上,提交评论中的自定义 on-comment 命令只能在仓库默认分支上运行。使用默认命令前缀(请参阅拉取请求和合并请求中的命令)时,/test <pipelinerun-name> branch:<branch> 是唯一一种在两个 Provider 中 PAC 接受评论的所有位置都能使用的形式。<pipelinerun-name> 始终是 .tekton/ 文件中的 metadata.name 或 metadata.generateName,而不是生成的运行时名称,因此请为每个 PipelineRun 设置一个贡献者可以输入的稳定名称。评论命令规则如下:要从 .tekton/ 运行或重新运行 PipelineRun,以及要从提交评论中选择分支,请使用内置的 /test 或 /retest;仅在执行其他特定于仓库的操作时使用 on-comment,例如 /deploy-preview(请参阅自动事件触发器)。on-comment 为 Technology Preview。
前提条件。评论事件必须传递到 PAC。使用 webhook 时(GitLab,或 Webhook 模式下的 GitHub),自动 webhook 注册会订阅这些事件,具体列于配置 GitLab 仓库和配置 GitHub 仓库中;在 GitHub Webhook 模式下,PAC 仍会拒绝提交评论,因此只有拉取请求评论可以触发 PipelineRun。使用 GitHub App 时,App 会改为传递这些事件,并且必须订阅 Commit comment 和 Issue comment,具体列于手动创建 GitHub App中。评论者必须获得运行 PAC 命令的授权;对于提交评论,被评论的提交必须是 branch:<branch> 中指定分支的 HEAD。
后续步骤
- 在 Git 中定义 PipelineRun - PipelineRun 文件和触发器注释
- 传入 Webhook - 用于外部系统的直接 HTTP 触发器
- 常见问题 - 故障排除指南