触发 PAC Pipeline

面向普通用户

本页面介绍在连接仓库后,PAC 如何启动 PipelineRun。要定义 PAC 选择的 .tekton/ 文件,请参阅在 Git 中定义 PipelineRun。

PAC 通过三种方式触发 Pipeline:

  • 自动事件触发器:Git provider 发送 webhook 事件,PAC 将这些事件与 PipelineRun 文件上的注解进行匹配。
  • 评论命令触发器:授权用户使用 PAC 命令发表评论,例如 /test、/retest 或 /cancel。
  • 传入 webhook 触发器:外部系统向 PAC controller 的 /incoming endpoint 发送 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。

事件源PAC event匹配条件
分支推送push推送的分支与 PipelineRun 分支过滤器匹配。
标签推送push标签 ref 与 PipelineRun 标签过滤器匹配。
Pull Request / Merge Requestpull_requestPR/MR 的目标分支与 PipelineRun 分支过滤器匹配。
标签更新pull_requestPR/MR 具有匹配的标签条件。
自定义 PR/MR 评论on-comment新的 PR/MR 评论与 PipelineRun 评论正则表达式匹配。

对于特定于仓库的命令(例如 /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 无论该设置如何,均使用 /:

命令效果
/test为当前 PR 或 MR 运行所有匹配的 PipelineRun。
/test <pipelinerun>仅运行指定的 PipelineRun。
/retest重新运行对于同一提交没有成功运行记录的匹配 PipelineRun。PAC 根据 Repository namespace 中仍然存在的 PipelineRun,以及 GitLab 上该提交的提交状态,决定哪些 Pipeline 符合条件;在 GitHub 上,被 Pruner 或用户删除的运行不再计入。
/retest <pipelinerun>仅重新运行指定的 PipelineRun。
/cancel取消与该 PR 或 MR 关联的正在运行的 PipelineRun。
/cancel <pipelinerun>仅取消指定的 PipelineRun。
/ok-to-test当策略要求审批时,允许 PAC 为外部贡献或其他不受信任的贡献运行 CI。
/ok-to-test <sha>与 /ok-to-test 相同,但在 PAC 配置要求时执行显式 SHA 验证。

<pipelinerun> 是 .tekton/ 文件中的 metadata.name 或 metadata.generateName 值,而不是生成的运行时名称。例如,如果文件中包含 generateName: sv-event-pr-,请使用:

/test 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>:

/test <pipelinerun> 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>:

/test <pipelinerun> tag:<tag>

/retest 和 /cancel 也接受相同的分支参数。在 GitHub 标签评论中,两者也都接受标签参数。在 GitLab 上,/retest 以与 /test 相同的方式接受标签参数:

/retest <pipelinerun> branch:<branch>
/cancel <pipelinerun> branch:<branch>
/retest <pipelinerun> tag:<tag>

在命令中传递参数

在命令中传递参数属于 Technology Preview。内置命令可以包含 key=value 参数。PAC 会从评论中解析这些参数,并可使用它们覆盖 Repository.spec.params 中定义的自定义参数或受支持的标准变量:

/test <pipelinerun> environment=staging
/test <pipelinerun> message="run smoke tests"

只有已为 Repository 定义或 PAC 能够识别的参数才会应用。任意键都会被忽略。

Provider 说明

区域GitHubGitLab
PR/MR 事件Pull Request 事件匹配 on-event 值 pull_request。Merge Request 事件匹配 on-event 值 pull_request;{{ event_type }} 保存 Merge Request 或 pull_request_labeled(请参阅参数化提交和 URL)。
PR/MR 评论内置命令和 on-comment 可在已打开的 Pull Request 上运行。内置命令和 on-comment 可在已打开的 Merge Request 上运行。
提交评论仅适用于 GitHub App。在 GitHub Webhook 模式下,PAC 会使用 no github client has been initialized, exiting... (hint: did you forget setting a secret on your repo?) 拒绝每条提交评论,并且不会创建 PipelineRun。使用 GitHub App 时,/test、/retest 和 /cancel 可用于提交评论。其他评论会根据 on-comment 进行匹配,匹配的 PipelineRun 会在仓库默认分支上运行;提交评论无法通过这种方式选择其他分支。只有 /test、/retest 和 /cancel 可用于提交评论;其他提交评论(包括自定义的 on-comment 命令)都会被忽略。
标签评论命令tag:<tag> 仅适用于使用 GitHub App 的提交评论,不适用于 GitHub Webhook 模式。tag:<tag> 可在提交评论中与 /test 和 /retest 配合使用。被评论的提交必须是标签指向的提交。
/ok-to-test <sha>PAC 配置要求时会使用 SHA 验证。该命令支持 MR 授权;SHA 验证是 GitHub 特有的安全措施。

有关命令的更多详细信息,请参阅 Pipelines as Code GitOps 命令文档。

验证触发器

发送事件或评论后,检查定义了 Repository CR 的命名空间中的 PipelineRun:

kubectl get pipelineruns -n <namespace>

如果未创建任何 PipelineRun,请先检查事件注释。PAC 会将某些原因记录为 Repository 上的事件,例如,当 /test 指定的 PipelineRun 不在 .tekton/ 中时,会记录 cannot find the targeted pipelinerun <pipelinerun> in this repository。请在 Repository 命名空间中读取这些事件;事件只会保留有限时间,因此请在事件发生后尽快检查:

kubectl describe repository <repository-name> -n <namespace>

与任何 PipelineRun 都不匹配的事件,以及 PAC 拒绝的提交评论,不会记录在 Repository 中;其原因会记录在 PAC 控制器日志中。读取该日志需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常需要集群管理员权限。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会输出最后 10 行,因此该命令会读取最近 10 分钟内的每一行;如果事件发生时间更早,请增大 --since:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1

常见检查项:

症状检查
推送后未运行文件位于 .tekton/ 下,on-event 包含 push,并且 on-target-branch 与推送的 ref 匹配。
PR 或 MR 更新后未运行on-event 包含 pull_request,并且 on-target-branch 与 PR/MR 基分支匹配。
/test <pipelinerun> 不匹配使用 .tekton/ 文件中的 name 或 generateName,而不是生成的运行时 PipelineRun 名称。
提交评论未运行在 GitHub 上,仓库通过 GitHub App 连接:在 GitHub Webhook 模式下,PAC 会拒绝每条提交评论(请参阅 Provider 说明)。被评论的提交是所选 branch: 的 HEAD,或 tag: 指向的提交。
on-comment 未运行新评论在去除开头和结尾的空格后,必须与正则表达式匹配。

平台约定

启用时机。当多个仓库共用一个 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。

后续步骤