在 Git 中定义 PipelineRun

For Regular Users

本指南适用于在 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 会创建多个 PipelineRuns。

选择 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 Resolver 和 PAC pipeline resolution documentation。

集群中定义的 Pipeline

如果 Pipeline 已经由集群管理，例如由 platform 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。

Annotation	Purpose
`pipelinesascode.tekton.dev/on-event`	匹配 `push` 或 `pull_request` 等事件类型
`pipelinesascode.tekton.dev/on-target-branch`	匹配目标分支或 tag
`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]"

匹配自定义评论

将 on-comment 用于特定于仓库的 pull request 或 merge request 命令。该值是一个正则表达式，会在 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 处于 Technology Preview。若希望使用 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 处于 Technology Preview。它仍然依赖 on-event 和 on-target-branch。它受 GitHub、Gitea 和 GitLab 仓库支持，但不支持 Bitbucket 仓库。

分支规范

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

Match	Value
Exact branch	`[main]`
Multiple branches	`[main, release-nightly]`
Full branch ref	`[refs/heads/main]`
Branch glob	`[refs/heads/feature/*]`
Tag glob	`[refs/tags/1.*]`

分支和路径过滤

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

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

路径变更注解处于 Technology Preview。如果设置了 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.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"

参数化 Commit 和 URL

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

Variable	Description	Availability
`{{ body }}`	Webhook payload body	All events
`{{ event_type }}`	PAC event type, such as `push` or `pull_request`	All events
`{{ git_auth_secret }}`	Generated Git authentication Secret name	Private repositories
`{{ git_tag }}`	Git tag name	Tag push events
`{{ headers }}`	Webhook request headers	All events
`{{ pull_request_labels }}`	Pull request or merge request labels separated by newlines	Pull request events
`{{ pull_request_number }}`	Pull or merge request number	Pull request events
`{{ repo_owner }}`	Repository owner	All events
`{{ repo_name }}`	Repository name	All events
`{{ repo_url }}`	Repository URL	All events
`{{ revision }}`	Commit SHA	All events
`{{ sender }}`	Event sender	All events
`{{ source_branch }}`	Source branch	All events
`{{ source_url }}`	Source repository URL	All events
`{{ target_branch }}`	Target branch	All events
`{{ target_namespace }}`	PAC 创建 `PipelineRun` 的命名空间	All events
`{{ trigger_comment }}`	触发运行的评论	GitOps command triggers

示例：

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

对于私有仓库，当 Repository 引用了 Git access token 时，{{ 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 Resolver。

故障排查

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

有用的检查：

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

下一步

PAC Resolver - 远程 task 和 Pipeline 源
PAC documentation - Pipelines as Code 文档
Trigger PAC Pipelines - 自动事件和评论命令
Guides - 仓库设置步骤
Common Issues - 故障排查指南

#在 Git 中定义 PipelineRun

#目录

#Pipeline 文件位置

#选择 Pipeline 定义场景

#使用 pipelineSpec 以内联方式定义 Pipeline

#使用 pipelineRef 引用 Pipeline

#Git 中定义的 Pipeline

#集群中定义的 Pipeline

#触发事件

#将 Pull Request 事件匹配到 PipelineRun

#将 Push 事件匹配到 PipelineRun

#匹配自定义评论

#匹配 Pull Request 标签

#分支规范

#分支和路径过滤

#高级事件匹配

#进行中取消

#参数化 Commit 和 URL

#Task 解析

#故障排查

#下一步