管理流水线运行 | 代码即流水线 | Red Hat OpenShift Pipelines 1.17

使用代码即流水线创建流水线运行
使用代码即流水线运行流水线运行
使用代码即流水线重新启动或取消流水线运行
使用代码即流水线监控流水线运行状态
使用代码即流水线清理流水线运行
将传入 Webhook 与代码即流水线一起使用
其他资源

使用代码即流水线，您可以在代码库中创建流水线并运行这些流水线。

使用代码即流水线创建流水线运行

要使用代码即流水线运行流水线，您可以将流水线运行定义或模板作为 YAML 文件创建在代码库的 .tekton/ 目录中。您可以使用远程 URL 引用其他代码库中的 YAML 文件，但流水线运行仅由包含 .tekton/ 目录的代码库中的事件触发。

代码即流水线解析器将流水线运行与所有任务捆绑在一起，作为一个单独的流水线运行，无需外部依赖。

对于流水线，请至少使用一个带有规范的流水线运行，或一个单独的 Pipeline 对象。
对于任务，请将任务规范嵌入到流水线中，或将其单独定义为 Task 对象。

参数化提交和 URL

您可以使用带有 {{<var>}} 格式的动态、可扩展变量来指定提交和 URL 的参数。目前，您可以使用以下变量：

{{repo_owner}}：代码库所有者。
{{repo_name}}：代码库名称。
{{repo_url}}：代码库完整 URL。
{{revision}}：提交的完整 SHA 修订版。
{{sender}}：提交发送者的用户名或帐户 ID。
{{source_branch}}：事件发起的分支名称。
{{target_branch}}：事件目标的分支名称。对于推送事件，它与 source_branch 相同。
{{pull_request_number}}：拉取请求或合并请求编号，仅针对 pull_request 事件类型定义。
{{git_auth_secret}}：自动生成的密钥名称，其中包含 Git 提供商的令牌，用于检出私有代码库。

将事件与流水线运行匹配

您可以通过在流水线运行上使用特殊注释来将不同的 Git 提供商事件与每个流水线运行匹配。如果有多个流水线运行与事件匹配，代码即流水线会并行运行它们，并在流水线运行完成后将结果发布到 Git 提供商。

将拉取事件与流水线运行匹配

您可以使用以下示例将 pipeline-pr-main 流水线运行与目标为 main 分支的 pull_request 事件匹配：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-pr-main
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[main]" (1)
  pipelinesascode.tekton.dev/on-event: "[pull_request]"
# ...

1	您可以通过添加以逗号分隔的条目来指定多个分支。例如，`"[main, release-nightly]"`。此外，您可以指定以下内容：分支的完整引用，例如 `"refs/heads/main"` 具有模式匹配的通配符，例如 `"refs/heads/\"` 标签，例如 `"refs/tags/1.\"`

将推送事件与流水线运行匹配

您可以使用以下示例将 pipeline-push-on-main 流水线运行与目标为 refs/heads/main 分支的 push 事件匹配：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-push-on-main
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" (1)
  pipelinesascode.tekton.dev/on-event: "[push]"
# ...

1	您可以通过添加以逗号分隔的条目来指定多个分支。例如，`"[main, release-nightly]"`。此外，您可以指定以下内容：分支的完整引用，例如 `"refs/heads/main"` 具有模式匹配的通配符，例如 `"refs/heads/\"` 标签，例如 `"refs/tags/1.\"`

将评论事件与流水线运行匹配

您可以使用以下示例将 pipeline-comment 流水线运行与拉取请求上的评论匹配，当评论文本与 ^/merge-pr 正则表达式匹配时：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-comment
annotations:
  pipelinesascode.tekton.dev/on-comment: "^/merge-pr"
# ...

只有评论作者满足以下条件之一时，流水线运行才会启动

作者是仓库的所有者。
作者是仓库的协作者。
作者是仓库所在组织的公共成员。
评论作者列在仓库根目录下的OWNERS文件的approvers或reviewers部分，如Kubernetes文档中所定义。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规范。如果OWNERS文件包含filters部分，Pipelines as Code 只会针对.*过滤器匹配审批者和审阅者。

将评论事件与流水线运行匹配是仅供技术预览的功能。技术预览功能不受 Red Hat 生产服务级别协议 (SLA) 的支持，并且可能功能不完整。Red Hat 不建议在生产环境中使用它们。这些功能可以提前访问即将推出的产品功能，使客户能够在开发过程中测试功能并提供反馈。

有关 Red Hat 技术预览功能的支持范围的更多信息，请参阅技术预览功能支持范围。

高级事件匹配

Pipelines as Code 支持使用基于通用表达式语言 (CEL) 的过滤来进行高级事件匹配。如果您的流水线运行中包含pipelinesascode.tekton.dev/on-cel-expression批注，Pipelines as Code 将使用 CEL 表达式并跳过on-target-branch批注。与简单的on-target-branch批注匹配相比，CEL 表达式允许进行复杂的过滤和否定。

要在 Pipelines as Code 中使用基于 CEL 的过滤，请考虑以下批注示例

匹配目标分支为main分支且来自wip分支的pull_request事件

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-advanced-pr
annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && target_branch == "main" && source_branch == "wip"
...

要仅在路径发生更改时运行流水线，您可以将.pathChanged后缀函数与通配符模式一起使用

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-advanced-pr-pathchanged
annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && "docs/\*.md".pathChanged() (1)
# ...

1	匹配`docs`目录中的所有 markdown 文件。

匹配所有标题以[DOWNSTREAM]开头的拉取请求。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-advanced-pr-downstream
annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request && event_title.startsWith("[DOWNSTREAM]")
# ...

在pull_request事件上运行流水线，但跳过experimental分支。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-advanced-pr-not-experimental
annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && target_branch != experimental"
# ...

在使用 Pipelines as Code 时，对于基于 CEL 的高级过滤，您可以使用以下字段和后缀函数

event：push或pull_request事件。
target_branch：目标分支。
source_branch：pull_request事件的源分支。对于push事件，它与target_branch相同。
event_title：匹配事件的标题，例如push事件的提交标题，以及pull_request事件的拉取或合并请求的标题。目前，仅支持 GitHub、Gitlab 和 Bitbucket Cloud。
.pathChanged：字符串的后缀函数。该字符串可以是路径的通配符，用于检查路径是否已更改。目前，仅支持 GitHub 和 Gitlab。

此外，您可以访问 Git 代码库提供程序传递的完整有效负载。使用headers字段访问有效负载的标头，例如headers['x-github-event']。使用body字段访问有效负载的主体，例如body.pull_request.state。

使用有效负载的标头和主体进行基于 CEL 的 Pipelines as Code 过滤仅是技术预览功能。技术预览功能不受 Red Hat 生产服务级别协议 (SLA) 的支持，并且可能功能不完整。Red Hat 不建议在生产环境中使用它们。这些功能可以提前访问即将推出的产品功能，使客户能够在开发过程中测试功能并提供反馈。

有关 Red Hat 技术预览功能的支持范围的更多信息，请参阅技术预览功能支持范围。

在以下示例中，只有在以下所有条件都为真时，流水线运行才会启动

拉取请求的目标分支是main分支。
拉取请求的作者是superuser。
操作是synchronize；此操作在拉取请求发生更新时触发。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      body.pull_request.base.ref == "main" &&
        body.pull_request.user.login == "superuser" &&
        body.action == "synchronize"
# ...

如果您使用header或body字段进行事件匹配，则可能无法使用诸如retest之类的 Git 命令触发流水线运行。如果您使用 Git 命令，则有效负载主体是包含此命令的注释，而不是原始有效负载。

如果您在使用body字段进行事件匹配时想要再次触发流水线运行，您可以关闭并重新打开拉取请求或合并请求，或者添加新的 SHA 提交，例如使用以下命令

git commit --amend --no-edit && git push --force-with-lease

使用临时 GitHub App 令牌进行 Github API 操作

您可以使用 Pipelines as Code 从 GitHub App 生成的临时安装令牌来访问 GitHub API。令牌值存储在为私有仓库生成的临时{{git_auth_secret}}动态变量的git-provider-token键中。

例如，要向拉取请求添加注释，您可以使用来自 Tekton Hub 的github-add-comment任务以及 Pipelines as Code 批注。

...
  pipelinesascode.tekton.dev/task: "github-add-comment"
...

然后，您可以将任务添加到流水线运行定义中的tasks部分或finally任务中。

[...]
tasks:
  - name:
      taskRef:
        name: github-add-comment
      params:
        - name: REQUEST_URL
          value: "{{ repo_url }}/pull/{{ pull_request_number }}" (1)
        - name: COMMENT_OR_FILE
          value: "Pipelines as Code IS GREAT!"
        - name: GITHUB_TOKEN_SECRET_NAME
          value: "{{ git_auth_secret }}"
        - name: GITHUB_TOKEN_SECRET_KEY
          value: "git-provider-token"
...

1	通过使用动态变量，您可以将此代码片段模板重用于任何仓库的任何拉取请求。

在 GitHub Apps 上，生成的安装令牌可用 8 小时，并作用于事件源仓库，除非在集群中进行了不同的配置。

其他资源

CEL 语言规范

使用 Pipelines as Code 运行流水线运行

在默认配置下，当仓库发生指定的事件（例如拉取请求或推送）时，Pipelines as Code 会运行仓库默认分支.tekton/目录中的任何流水线运行。例如，如果默认分支上的流水线运行具有批注pipelinesascode.tekton.dev/on-event: "[pull_request]"，则每当发生拉取请求事件时，它都会运行。

在拉取请求或合并请求的情况下，如果拉取请求的作者满足以下条件，Pipelines as Code 还会运行来自默认分支以外的分支的流水线

作者是仓库的所有者。
作者是仓库的协作者。
作者是仓库所在组织的公共成员。
拉取请求作者列在仓库根目录下的OWNERS文件的approvers或reviewers部分，如Kubernetes文档中所定义。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规范。如果OWNERS文件包含filters部分，Pipelines as Code 只会针对.*过滤器匹配审批者和审阅者。

如果拉取请求作者不满足要求，则满足要求的其他用户可以在拉取请求中评论/ok-to-test，并启动流水线运行。

流水线运行执行

流水线运行始终在与生成事件的仓库关联的Repository自定义资源定义 (CRD) 的命名空间中运行。

您可以使用tkn pac CLI 工具观察流水线运行的执行情况。

要跟踪上次流水线运行的执行情况，请使用以下示例
```
$ tkn pac logs -n <my-pipeline-ci> -L (1)
```
1 my-pipeline-ci 是Repository CRD 的命名空间。
要交互式地跟踪任何流水线运行的执行情况，请使用以下示例
```
$ tkn pac logs -n <my-pipeline-ci> (1)
```
1 my-pipeline-ci 是Repository CRD 的命名空间。如果您需要查看除最后一次之外的流水线运行，可以使用tkn pac logs 命令选择附加到仓库的PipelineRun

如果您已使用 GitHub 应用配置了代码流水线，则代码流水线会在 GitHub 应用的**检查**选项卡中发布一个 URL。您可以点击 URL 并跟踪流水线执行。

使用代码流水线重新启动或取消流水线运行

您可以重新启动或取消没有事件的流水线运行，例如向您的分支发送新的提交或提出拉取请求。要重新启动所有流水线运行，请使用 GitHub 应用中的**重新运行所有检查**功能。

要重新启动所有或特定流水线运行，请使用以下注释

/test 和/retest 注释将重新启动所有流水线运行。
/test <pipeline_run_name> 和/retest <pipeline_run_name> 注释启动或重新启动特定的流水线运行。您可以使用此命令启动仓库上的任何代码流水线流水线运行，无论它是否由此流水线运行的事件触发。

要取消所有或特定流水线运行，请使用以下注释

/cancel 注释将取消所有流水线运行。
/cancel <pipeline_run_name> 注释将取消特定的流水线运行。

注释的结果显示在 GitHub 应用的**检查**选项卡下。

只有当注释作者满足以下要求之一时，注释才会启动、重新启动或取消任何流水线运行

作者是仓库的所有者。
作者是仓库的协作者。
作者是仓库所在组织的公共成员。
评论作者列在仓库根目录下的OWNERS文件的approvers或reviewers部分，如Kubernetes文档中所定义。Pipelines as Code 支持OWNERS和OWNERS_ALIASES文件的规范。如果OWNERS文件包含filters部分，Pipelines as Code 只会针对.*过滤器匹配审批者和审阅者。

使用注释启动与事件不匹配的流水线运行仅为技术预览功能。技术预览功能不受 Red Hat 生产服务级别协议 (SLA) 的支持，并且可能功能不完整。Red Hat 不建议在生产环境中使用它们。这些功能提供对即将推出的产品功能的早期访问，使客户能够在开发过程中测试功能并提供反馈。

有关 Red Hat 技术预览功能的支持范围的更多信息，请参阅技术预览功能支持范围。

步骤

如果您定位拉取请求并使用 GitHub 应用，请转到**检查**选项卡并点击**重新运行所有检查**。
如果您定位拉取或合并请求，请在您的拉取请求中使用注释
取消所有流水线运行的示例注释
```
This is a comment inside a pull request.
/cancel
```

如果您定位推送请求，请在您的提交消息中包含注释。

此功能仅支持 GitHub 提供商。

转到您的 GitHub 仓库。
点击**提交**部分。
点击您要重新启动流水线运行的提交。

点击您要添加注释的行号。

启动或重新启动特定流水线运行的示例注释

This is a comment inside a commit.
/retest example_pipeline_run

如果您在推送请求中多个分支中存在的提交上运行命令，则将使用具有最新提交的分支。

这会导致两种情况

如果您在提交上运行没有参数的命令，例如/test，则测试将自动在main分支上执行。
如果您包含分支规范，例如/test branch:user-branch，则测试将在注释所在的提交上执行，并带有user-branch分支的上下文。

使用代码流水线监控流水线运行状态

根据上下文和支持的工具，您可以通过不同的方式监控流水线运行的状态。

GitHub 应用上的状态

流水线运行完成后，状态将添加到**检查**选项卡中，其中包含有关流水线每个任务耗时以及tkn pipelinerun describe命令输出的有限信息。

日志错误片段

当代码流水线检测到流水线其中一个任务中的错误时，将显示一个小的片段，其中包含第一个失败任务的任务分解中的最后 3 行。

代码流水线通过查看流水线运行并将秘密值替换为隐藏字符来避免泄露秘密。但是，代码流水线无法隐藏来自工作区和envFrom源的秘密。

日志错误片段的注释

在TektonConfig自定义资源的pipelinesAsCode.settings规范中，您可以将error-detection-from-container-logs参数设置为true。在这种情况下，代码流水线将从容器日志中检测错误，并将它们作为注释添加到发生错误的拉取请求中。

添加日志错误片段的注释仅为技术预览功能。技术预览功能不受 Red Hat 生产服务级别协议 (SLA) 的支持，并且可能功能不完整。Red Hat 不建议在生产环境中使用它们。这些功能提供对即将推出的产品功能的早期访问，使客户能够在开发过程中测试功能并提供反馈。

有关 Red Hat 技术预览功能的支持范围的更多信息，请参阅技术预览功能支持范围。

目前，代码流水线仅支持错误看起来像makefile或grep输出的以下格式的简单情况

<filename>:<line>:<column>: <error message>

您可以使用error-detection-simple-regexp参数自定义用于检测错误的正则表达式。正则表达式使用命名组来灵活指定匹配方式。需要匹配的组是filename、line和error。您可以查看代码流水线配置映射以获取默认正则表达式。

默认情况下，代码流水线仅扫描容器日志的最后 50 行。您可以在error-detection-max-number-of-lines字段中增加此值，或设置-1以获得无限行数。但是，此类配置可能会增加观察程序的内存使用量。

webhook 状态

对于 webhook，当事件是拉取请求时，状态将作为注释添加到拉取或合并请求中。

故障

如果命名空间与Repository自定义资源定义 (CRD) 匹配，则代码流水线会在命名空间内的 Kubernetes 事件中发出其故障日志消息。

与 Repository CRD 关联的状态

流水线运行的最后 5 个状态消息存储在Repository自定义资源中。

$ oc get repo -n <pipelines-as-code-ci>

NAME                  URL                                                        NAMESPACE             SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
pipelines-as-code-ci   https://github.com/openshift-pipelines/pipelines-as-code   pipelines-as-code-ci   True        Succeeded   59m         56m

使用tkn pac describe命令，您可以提取与您的仓库及其元数据关联的运行状态。

通知

代码流水线不管理通知。如果您需要通知，请使用流水线的finally功能。

其他资源

用于克隆私有仓库的git-clone任务示例

使用代码流水线清理流水线运行

用户命名空间中可能存在许多流水线运行。通过设置max-keep-runs注释，您可以配置代码流水线以保留与事件匹配的有限数量的流水线运行。例如

...
  pipelinesascode.tekton.dev/max-keep-runs: "<max_number>" (1)
...

代码流水线在成功执行后立即开始清理，仅保留使用注释配置的最大数量的流水线运行。

流水线即代码会跳过清理正在运行的流水线，但会清理掉状态未知的流水线运行。
流水线即代码会跳过清理失败的拉取请求。

使用传入 Webhook 与流水线即代码

使用传入 Webhook URL 和共享密钥，您可以在仓库中启动流水线运行。

要使用传入 Webhook，请在Repository自定义资源定义 (CRD) 的spec部分中指定以下内容：

流水线即代码匹配的传入 Webhook URL。
Git 提供程序和用户令牌。目前，流水线即代码支持github、gitlab和bitbucket-cloud。

在 GitHub 应用上下文中使用传入 Webhook URL 时，必须指定令牌。
目标分支和传入 Webhook URL 的密钥。

示例：带有传入 Webhook 的Repository CRD

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: repo
  namespace: ns
spec:
  url: "https://github.com/owner/repo"
  git_provider:
    type: github
    secret:
      name: "owner-token"
  incoming:
    - targets:
      - main
      secret:
        name: repo-incoming-secret
      type: webhook-url

示例：传入 Webhook 的repo-incoming-secret 密钥

apiVersion: v1
kind: Secret
metadata:
  name: repo-incoming-secret
  namespace: ns
type: Opaque
stringData:
  secret: <very-secure-shared-secret>

要触发位于 Git 仓库.tekton目录中的流水线运行，请使用以下命令：

$ curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'

流水线即代码会匹配传入的 URL 并将其视为push事件。但是，流水线即代码不会报告由此命令触发的流水线运行状态。

要获取报告或通知，请使用finally任务直接将其添加到您的流水线中。或者，您可以使用tkn pac CLI 工具检查Repository CRD。