在 Git 中定义 PipelineRuns

面向普通用户

本指南适用于在 Git 仓库中定义 PAC PipelineRun 清单的普通用户。

PAC 会从 .tekton/ 中读取 Tekton PipelineRun 清单，将其与 Git 事件进行匹配，并在 Repository CR 的命名空间中创建匹配的 PipelineRun。

Pipeline 文件位置

PAC 会处理 .tekton/ 下面所有 .yaml 和 .yml 文件：

your-repo/
├── .tekton/
│   ├── pipelinerun.yaml
│   ├── test-pipeline.yaml
│   └── deploy-pipeline.yaml
└── src/

每个 PipelineRun 都会单独评估。如果多个文件匹配同一个事件，PAC 会创建多个 PipelineRun。

选择 Pipeline 定义场景

选择 PipelineRun 用于定义要运行的工作方式：直接在 pipelineSpec 中内联定义，或通过 pipelineRef 引用可复用的 Pipeline。

使用 `pipelineSpec` 直接定义 Pipeline

当 Pipeline 逻辑应直接位于与触发器定义相同的 Git 文件中时，请使用 pipelineSpec：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from PAC!"

使用 `pipelineRef` 引用 Pipeline

当 PipelineRun 需要复用某个 Pipeline 定义时，请使用 pipelineRef。

定义在 Git 中的 Pipeline

在默认的 remote-tasks: "true" 下，普通的 pipelineRef.name 应引用 PAC 可以从 Git 中解析出的 Pipeline。 PAC 会先检查 pipelinesascode.tekton.dev/pipeline 注解，然后检查 .tekton/ 及其子目录下的 Pipeline 文件。

常见布局：

.tekton/
├── pipelinerun.yaml
└── pipeline.yaml

pipeline.yaml：

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: my-pipeline-resource
spec:
  tasks:
  - name: hello
    taskSpec:
      steps:
      - name: echo
        image: alpine:latest
        script: |
          echo "Hello from a Pipeline in Git"

pipelinerun.yaml：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineRef:
    name: my-pipeline-resource

对于其他 Pipeline 来源，请使用 pipelinesascode.tekton.dev/pipeline。请参阅 PAC 解析器和 PAC pipeline 解析文档。

定义在集群中的 Pipeline

如果 Pipeline 已经由集群管理，例如由平台 Pipeline 产品管理，请使用以下方法之一。

保持 remote-tasks: "true"，并使用 Tekton cluster resolver 通过带命名空间的 Pipeline 进行引用：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineRef:
    resolver: cluster
    params:
    - name: kind
      value: pipeline
    - name: name
      value: my-pipeline-resource
    - name: namespace
      value: my-namespace

请保留 namespace 参数，除非 cluster resolver 已配置默认命名空间。如果该参数和 resolver 默认命名空间都为空，则解析失败。

另一种方式是由管理员在 PAC 组件配置中设置 remote-tasks: "false"。在该模式下，普通的 pipelineRef.name 可以引用与生成的 PipelineRun 位于同一命名空间中的 Pipeline：

spec:
  pipelineRef:
    name: my-pipeline-resource

在此模式下，PAC 不会内联或解析该 Pipeline。Tekton 会在 PAC 创建 PipelineRun 后解析该引用，因此 Pipeline 必须已存在于目标命名空间中，并且运行时 ServiceAccount 必须具有使用它的权限。

触发事件

选择 pipelineSpec 或 pipelineRef 后，添加 PAC 注解以控制哪些 Git 事件会触发 PipelineRun。

注解	作用
`pipelinesascode.tekton.dev/on-event`	匹配 `push` 或 `pull_request` 等事件类型
`pipelinesascode.tekton.dev/on-target-branch`	匹配目标分支或标签
`pipelinesascode.tekton.dev/on-comment`	使用正则表达式匹配自定义的 pull request 或 merge request 评论
`pipelinesascode.tekton.dev/on-label`	匹配 pull request 或 merge request 标签
`pipelinesascode.tekton.dev/on-cel-expression`	使用 CEL 进行高级匹配

将 Pull Request 事件与 PipelineRun 匹配

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"

将 Push 事件与 PipelineRun 匹配

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"

匹配自定义评论

当您需要为仓库特定的 pull request 或 merge request 命令设置触发条件时，请使用 on-comment。该值是一个正则表达式，会在 PAC 去除前后空格和换行后，与新评论进行匹配：

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-comment: "^/deploy-preview$"

on-comment 为技术预览功能。当您希望使用 PAC 的原生命令行为而不是仓库特定触发器时，请使用内置的 GitOps 命令，例如 /test、/retest 和 /cancel。

匹配 Pull Request 标签

当 PipelineRun 仅应针对具有匹配标签的 pull request 或 merge request 运行时，请使用 on-label：

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-label: "[ready-for-ci]"

on-label 为技术预览功能。它仍然依赖 on-event 和 on-target-branch。它支持 GitHub、Gitea 和 GitLab 仓库，但不支持 Bitbucket 仓库。

分支规范

on-target-branch 接受完整 ref、分支名、标签、glob 以及逗号分隔的值。

匹配方式	值
精确分支	`[main]`
多个分支	`[main, release-nightly]`
完整分支 ref	`[refs/heads/main]`
分支 glob	`[refs/heads/feature/*]`
标签 glob	`[refs/tags/1.*]`

分支和路径过滤

使用分支注解进行简单过滤：

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main, develop]"
    pipelinesascode.tekton.dev/on-event: "[push, pull_request]"

路径变更注解为技术预览功能。如果设置了 on-cel-expression，PAC 会忽略 on-path-change 和 on-path-change-ignore。

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-path-change: "[docs/**.md]"
    pipelinesascode.tekton.dev/on-path-change-ignore: "[docs/generated/**]"

高级事件匹配

对于复杂条件，请使用 pipelinesascode.tekton.dev/on-cel-expression。设置 CEL 后，PAC 会使用 CEL 表达式，并忽略 on-target-branch、on-event、on-label、on-path-change 和 on-path-change-ignore。

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      event == "pull_request" &&
      target_branch == "main" &&
      source_branch.startsWith("feature/")

常见的 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" 可在新运行开始时取消旧的匹配运行：

metadata:
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/cancel-in-progress: "true"

为提交和 URL 参数化

PAC 会在创建 PipelineRun 之前，将 {{ variable_name }} 格式中的动态变量替换掉。$(params.name) 等 Tekton 参数则由 Tekton 在后续处理。

变量	描述	可用性
`{{ body }}`	Webhook 负载正文	所有事件
`{{ event_type }}`	PAC 事件类型，例如 `push` 或 `pull_request`	所有事件
`{{ git_auth_secret }}`	生成的 Git 认证 Secret 名称	私有仓库
`{{ git_tag }}`	Git 标签名称	标签 push 事件
`{{ headers }}`	Webhook 请求头	所有事件
`{{ pull_request_labels }}`	以换行符分隔的 pull request 或 merge request 标签	pull request 事件
`{{ pull_request_number }}`	pull request 或 merge request 编号	pull request 事件
`{{ repo_owner }}`	仓库所有者	所有事件
`{{ repo_name }}`	仓库名称	所有事件
`{{ repo_url }}`	仓库 URL	所有事件
`{{ revision }}`	Commit SHA	所有事件
`{{ sender }}`	事件发送者	所有事件
`{{ source_branch }}`	源分支	所有事件
`{{ source_url }}`	源仓库 URL	所有事件
`{{ target_branch }}`	目标分支	所有事件
`{{ target_namespace }}`	PAC 创建 `PipelineRun` 的命名空间	所有事件
`{{ trigger_comment }}`	触发运行的评论	GitOps 命令触发

示例：

spec:
  params:
  - name: repo-url
    value: "{{ repo_url }}"
  - name: revision
    value: "{{ revision }}"

对于私有仓库，当 Repository 引用了 Git 访问令牌时，{{ git_auth_secret }} 可用。

Task 解析

PAC 可以嵌入由 PAC 注解引用的 task，或者您也可以直接使用 Tekton resolver 语法。

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: fetch
      taskRef:
        name: git-clone

有关支持的 task 和 Pipeline 来源，请参阅 PAC 解析器。

故障排查

问题	检查项
未创建 `PipelineRun`	确认文件位于 `.tekton/` 下，并且事件注解与 Git 事件匹配
未找到命名空间 Pipeline	在默认 `remote-tasks: "true"` 下，请使用 `pipelineRef.resolver: cluster`，或请管理员将 `remote-tasks: "false"`
变量未被替换	检查 `{{ variable_name }}` 语法以及事件特定的可用性
未找到远程任务	检查 task 注解名称、resolver 配置以及 PAC controller 日志

有用的检查：

kubectl get pipelineruns -n <namespace>
kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100

下一步

PAC 解析器 - 远程 task 和 Pipeline 来源
PAC 文档 - Pipelines as Code 文档
触发 PAC Pipelines - 自动事件和评论命令
指南 - 仓库设置演练
常见问题 - 故障排查指南

#在 Git 中定义 PipelineRuns

#目录

#Pipeline 文件位置

#选择 Pipeline 定义场景

#使用 pipelineSpec 直接定义 Pipeline

#使用 pipelineRef 引用 Pipeline

#定义在 Git 中的 Pipeline

#定义在集群中的 Pipeline

#触发事件

#将 Pull Request 事件与 PipelineRun 匹配

#将 Push 事件与 PipelineRun 匹配

#匹配自定义评论

#匹配 Pull Request 标签

#分支规范

#分支和路径过滤

#高级事件匹配

#运行中取消

#为提交和 URL 参数化

#Task 解析

#故障排查

#下一步