PAC 解析器

适用于普通用户

本指南面向普通用户，介绍如何使用 PAC 解析器，从本地仓库、Tekton Hub 和远程 URL 自动解析并嵌入任务和流水线。

本指南说明如何使用 Pipelines as Code (PAC) 解析器，自动从三种来源解析并嵌入任务和流水线：存储在仓库中的本地任务、来自 Tekton Hub 的远程任务，以及来自远程 Git 仓库或 HTTP URL 的任务。

前提条件

PAC 组件已部署并正在运行
已配置 Repository CR（请参阅配置 Repository）
理解 Tekton PipelineRun 结构

关于 PAC 解析器

PAC 解析器会自动获取远程任务和流水线，并将其嵌入到你的 PipelineRun 定义中。这样就不需要在流水线代码中手动定义任务，或使用 resolver 语法。

任务嵌入的工作方式

当 PAC 从 Tekton Hub 解析某个任务时：

PAC 从 Hub 获取任务定义（YAML）
PAC 将 taskRef 转换为 taskSpec，并将任务定义以内联方式嵌入到你的 PipelineRun 中
嵌入的任务会成为 PipelineRun 定义的一部分
该任务不需要在集群中作为单独的 Task 资源存在

这意味着你可以直接使用 Tekton Hub 中的任务，而无需手动复制其定义，也无需在集群中创建 Task 资源。

支持的来源

本地任务：在你的 Git 仓库中定义的任务（使用 taskSpec 或 resolver 语法）
Tekton Hub：来自 Tekton Hub 目录的任务和流水线
远程 URL：来自远程 Git 仓库或 HTTP URL 的任务和流水线

官方文档

如需了解 Pipelines as Code 远程解析功能的完整信息，请参阅：

PAC 解析器的工作原理

了解解析器工作流有助于你排查问题并优化流水线配置。

解析器工作流

当 PAC 处理带有 resolver 注解的 PipelineRun 时，会按以下步骤执行：

事件触发：Git 事件（push、pull request 等）触发 PAC controller
获取流水线：PAC controller 从你的 Git 仓库获取 PipelineRun 定义
检测注解：PAC controller 扫描注解中的 resolver 指令：
- pipelinesascode.tekton.dev/task: "task-name"
- pipelinesascode.tekton.dev/task-1: "task-name"
- pipelinesascode.tekton.dev/pipeline: "pipeline-name"
任务解析：对于每个任务注解：
- PAC controller 查询 Tekton Hub API（或已配置的 hub URL）
- 获取任务定义（YAML）
- 验证任务结构
任务嵌入：PAC 将解析后的任务定义嵌入到 PipelineRun 中：
- PAC 将 taskRef 转换为 taskSpec，并将任务定义以内联方式嵌入到每个任务条目中
- 嵌入的任务会成为 PipelineRun 定义的一部分，因此不需要在集群中作为单独的 Task 资源存在
创建 PipelineRun：PAC 在 Kubernetes 中创建包含嵌入任务的最终 PipelineRun
执行：Tekton Pipeline controller 接管该 PipelineRun 并执行它

详细示例：逐步解析

下面通过一个完整示例来演示解析器的工作方式：

第 1 步：原始 PipelineRun 定义

你在仓库中定义一个 PipelineRun（.tekton/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]"
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

第 2 步：PAC Controller 处理注解

当发生 push 事件时，PAC controller 会：

从 Git 读取 PipelineRun：PAC 从仓库中获取 .tekton/pipelinerun.yaml 文件
检测注解：PAC 扫描类似 pipelinesascode.tekton.dev/task: "git-clone" 的任务注解
解析任务名称和版本：
- 仅任务名称（例如 "git-clone"）：从 Hub 获取最新版本
- 带版本号（例如 "git-clone:0.1"）：获取指定版本
- 版本选择：
  - 未指定版本 → PAC 向 Hub 查询最新稳定版本
  - 指定版本（格式：task-name:version）→ PAC 获取该精确版本
  - 版本格式遵循语义化版本（例如 0.1、0.9、1.2.3）
查询 Tekton Hub API：
- Hub URL：默认为集群内部 Hub（http://tekton-hub-api.tekton-pipelines:8000/v1）或公共 Hub（https://api.hub.tekton.dev/v1）
- 查询最新版本：PAC 向 Hub 查询可用的最新版本
- 查询指定版本：PAC 请求注解中指定的精确版本
- 示例查询：
  - 最新："git-clone" → Hub 返回最新版本
  - 指定版本："git-clone:0.1" → Hub 返回 0.1 版本

从 Hub 接收任务定义：Hub 返回完整的 Task YAML：

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: git-clone
spec:
  params:
  - name: url
    description: git url to clone
  - name: revision
    description: revision to checkout
  steps:
  - name: clone
    image: gcr.io/tekton-releases/git-init
    script: |
      #!/bin/sh
      git clone $(params.url) $(workspaces.output.path)
      cd $(workspaces.output.path)
      git checkout $(params.revision)

版本选择最佳实践：

生产环境：指定精确版本（例如 "git-clone:0.1"），以保证可复现性和稳定性
开发/测试：使用最新版本（不带版本后缀），以便自动获得新功能和 bug 修复
版本固定：在生产环境中始终固定到特定版本，避免 Hub 更新带来的破坏性变更
版本更新：定期以受控方式审查并更新已固定的版本

第 3 步：PAC 将任务嵌入到 PipelineRun 中

PAC 通过将 taskRef 转换为 taskSpec，并嵌入解析后的任务定义来修改 PipelineRun：

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: fetch-code
      # PAC 将 taskRef 转换为 taskSpec 并嵌入任务定义
      taskSpec:
        params:
        - name: url
          description: git url to clone
        - name: revision
          description: revision to checkout
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
            cd $(workspaces.output.path)
            git checkout $(params.revision)
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

第 4 步：在 Kubernetes 中创建 PipelineRun

PAC 会在你的集群中创建最终的 PipelineRun。你可以验证它：

kubectl get pipelinerun my-pipeline -n <namespace> -o yaml

示例输出（已截断，显示嵌入的任务）：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      # 任务定义作为 taskSpec 嵌入
      taskSpec:
        params:
        - name: url
        - name: revision
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
      params:
        - name: url
          value: "https://gitlab.com/user/repo"
        - name: revision
          value: "abc1234"

解析时机

重要：任务解析发生在 PipelineRun 在 Kubernetes 中创建之前。这意味着：

任务是在流水线定义阶段解析的，而不是在执行阶段
如果某个任务无法解析，PipelineRun 创建将失败
你可以通过检查 Kubernetes 中的 PipelineRun YAML 来验证任务解析结果
PAC 会缓存已解析的任务以提升性能

验证任务解析

要验证任务是否已正确解析：

检查 Kubernetes 中的 PipelineRun：

kubectl get pipelinerun <name> -n <namespace> -o yaml

查看各个任务中是否存在带有 taskSpec 的嵌入任务：

spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskSpec:
        params:
        - name: url
        - name: revision
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
      params:
        - name: url
          value: "https://gitlab.com/user/repo"
        - name: revision
          value: "abc1234"

理解任务嵌入

PAC 通过将各个任务中的 taskRef 转换为 taskSpec 来嵌入已解析的任务。任务定义会以内联形式嵌入为 PipelineRun 的一部分，遵循标准 Tekton 语法。

检查 PAC Controller 日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i "task.*resolve"  # 将 <pac-namespace> 替换为你的实际命名空间（默认：tekton-pipelines）

示例输出（显示任务解析）：

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}

验证任务引用是否正确：

# 检查 taskRef.name 是否与注解中的任务名称匹配
kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.pipelineSpec.tasks[*].taskRef.name}'

示例输出：

git-clone golangci-lint

检查 PipelineRun 是否已成功创建：

kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.status.conditions[*].type}'

示例输出：

Succeeded

如果任务解析失败，PipelineRun 可能不会被创建，或者会带有包含错误消息的 Failed 条件。

使用本地任务

本地任务是直接在你的 Git 仓库中定义的任务。PAC 支持两种使用本地任务的方式：

内联任务定义（taskSpec）

你可以在 PipelineRun 中使用 taskSpec 直接定义任务：

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: build
      taskSpec:
        steps:
        - name: build
          image: golang:1.21
          script: |
            #!/bin/sh
            go build -o app ./cmd
    - name: test
      taskSpec:
        steps:
        - name: test
          image: golang:1.21
          script: |
            #!/bin/sh
            go test ./...

工作方式：

任务通过 taskSpec 以内联方式定义在流水线中的每个任务里
无需外部解析——任务本身就是 PipelineRun 定义的一部分
适用于简单、与仓库强相关的任务

引用仓库中的任务文件

你可以使用 PAC 注解和仓库内的特殊语法，引用存储在仓库中的任务文件。

重要：对于仓库中的任务，请使用 pipelinesascode.tekton.dev/task 或 pipelinesascode.tekton.dev/task-<N> 注解格式。

仓库结构：

.tekton/
├── pipelinerun.yaml
└── tasks/
    ├── build-task.yaml
    └── test-task.yaml

使用 PAC 注解的 PipelineRun 定义：

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]"
    # 使用相对路径引用本地任务
    pipelinesascode.tekton.dev/task: ".tekton/tasks/build-task.yaml"
    pipelinesascode.tekton.dev/task-1: ".tekton/tasks/test-task.yaml"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskRef:
        name: build-task
    - name: test
      taskRef:
        name: test-task
      runAfter: [build]

工作方式：

当你在任务注解中使用相对路径时，PAC 会自动解析并嵌入仓库中的任务
taskRef.name 中的任务名称应与 YAML 文件中定义的任务名称一致
与使用 resolver: git 语法相比，这种方式更简单，也是 PAC 推荐的方法

何时使用本地任务

在以下场景中使用本地任务：

任务专属于你的项目，不适合共享
你需要完全控制任务定义和版本
任务会随着代码库频繁变化
你希望将任务和流水线一起纳入版本控制

使用远程任务注解

你可以使用 PAC 注解引用来自 Tekton Hub 或远程 HTTP URL 的任务。PAC 会自动获取并将这些任务嵌入到你的 PipelineRun 中。

来自 Tekton Hub 的远程任务

引用 Tekton Hub 中的单个任务：

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]"
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

工作方式：

注解 pipelinesascode.tekton.dev/task: "git-clone" 告诉 PAC 从 Tekton Hub 获取 git-clone 任务
PAC 会自动将任务定义嵌入到你的 PipelineRun 中
然后你可以使用 taskRef.name: git-clone 来引用它

来自 HTTP URL 的远程任务

你也可以引用来自远程 HTTP URL 的任务：

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]"
    # 从远程 URL 引用任务
    pipelinesascode.tekton.dev/task: "https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.9/git-clone.yaml"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

工作方式：

PAC 从指定的 HTTP URL 获取任务定义
PAC 会自动将任务嵌入到你的 PipelineRun 中
taskRef.name 中的任务名称应与远程 YAML 文件中定义的任务名称一致

多个任务注解

使用编号注解引用多个任务：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/task: "git-clone"
    pipelinesascode.tekton.dev/task-1: "golangci-lint"
    pipelinesascode.tekton.dev/task-2: "buildah"
spec:
  pipelineSpec:
    tasks:
    - name: fetch
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"
    - name: lint
      taskRef:
        name: golangci-lint
      runAfter: [fetch]
    - name: build
      taskRef:
        name: buildah
      runAfter: [lint]

任务列表语法

你也可以使用方括号语法，在单个注解中指定多个任务：

metadata:
  annotations:
    pipelinesascode.tekton.dev/task-1: "[golangci-lint, buildah]"

这等价于：

metadata:
  annotations:
    pipelinesascode.tekton.dev/task-1: "golangci-lint"
    pipelinesascode.tekton.dev/task-2: "buildah"

任务版本指定

默认情况下，PAC 会从 Hub 获取任务的最新版本。若要指定某个特定版本，请使用 task-name:version 格式。

参考：有关远程任务解析的更多细节，请参阅 Red Hat OpenShift Pipelines as Code 文档。

最新版本（推荐用于开发）：

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone"

指定版本（推荐用于生产）：

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone:0.9"

带版本的多个任务：

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone:0.9"
    pipelinesascode.tekton.dev/task-1: "golangci-lint:0.4"
    pipelinesascode.tekton.dev/task-2: "buildah"  # 使用最新版本

自定义 Hub URL

默认的 hub-url 指向默认命名空间中的集群内部 Tekton Hub 服务（http://tekton-hub-api.tekton-pipelines:8000/v1）。如果 Tekton Hub 部署在其他命名空间，请相应调整 URL 中的命名空间。如果你需要使用不同的 Hub 实例，请在 OpenShiftPipelinesAsCode CR 中进行配置：

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    # 适用于位于其他命名空间中的集群内部 Hub
    hub-url: "http://tekton-hub-api.<your-namespace>:8000/v1"
    
    # 或者使用外部/公共 Hub
    hub-url: "https://api.hub.tekton.dev/v1"
    
    # 或者使用自定义 Hub 实例
    hub-url: "https://custom-hub.example.com/v1"

注意：只有 PAC controller 需要访问 Hub URL。如果使用集群内部 Hub，请确保 PAC controller 能够访问 Hub 服务。

使用远程流水线注解

使用场景有限

远程流水线注解在实际中很少使用。大多数用户会直接使用 pipelineSpec 在内联方式中定义流水线，而不是引用远程流水线。本节仅为完整性而保留。

你可以引用来自 Tekton Hub 的远程流水线，不过这比使用内联流水线定义更少见：

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]"
    # 从 Tekton Hub 引用远程流水线
    pipelinesascode.tekton.dev/pipeline: "pipeline-name"
spec:
  pipelineRef:
    name: pipeline-name
  params:
  - name: image-url
    value: "registry.example.com/myapp"

工作方式：

注解 pipelinesascode.tekton.dev/pipeline: "pipeline-name" 告诉 PAC 从 Tekton Hub 获取该流水线
PAC 会自动嵌入流水线定义
你可以通过 pipelineRef.name 引用它

注意：在大多数情况下，你应在仓库中使用 pipelineSpec 以内联方式定义流水线，而不是使用远程流水线。这样可以更好地对流水线定义进行版本控制并提升可见性。

组合远程任务和流水线

与 Resolver 语法的比较

PAC 注解为 Tekton 的 resolver 语法提供了更简单的替代方案：

使用 PAC 注解（推荐）

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

使用 Resolver 语法

spec:
  pipelineSpec:
    tasks:
    - name: clone
      taskRef:
        resolver: hub
        params:
        - name: name
          value: git-clone
        - name: kind
          value: task

PAC 注解的优势：

语法更简单
自动嵌入任务
无需指定 resolver 参数
可与 PAC 的任务解析无缝配合

故障排查

未找到任务

验证任务名称：检查 Tekton Hub 中的任务名称是否正确
检查 Hub URL：确认 hub URL 配置正确

查看 PAC 日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i task

示例输出：

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}

任务解析失败

检查网络连通性：确保 PAC controller 可以访问 Tekton Hub

# 从 PAC controller Pod 测试 Hub 连通性
kubectl exec -n <pac-namespace> \
  $(kubectl get pod -n <pac-namespace> -l app=pipelines-as-code-controller -o jsonpath='{.items[0].metadata.name}') \
  -- curl -I https://api.hub.tekton.dev/v1/resource/task/git-clone

示例输出（如果可访问）：

HTTP/1.1 200 OK
Content-Type: application/json

验证 Hub 配置：检查 OpenShiftPipelinesAsCode CR 中的 hub-url 设置

kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o jsonpath='{.spec.settings.hub-url}'

示例输出：

http://tekton-hub-api.tekton-pipelines:8000/v1

检查任务版本：确保指定的版本确实存在

# 查询 Tekton Hub 中可用的版本
curl https://api.hub.tekton.dev/v1/resource/task/git-clone

示例输出（已截断）：

{
  "id": 1,
  "name": "git-clone",
  "kind": "Task",
  "latestVersion": {
    "id": 1,
    "version": "0.9"
  },
  "versions": [
    {"version": "0.9"},
    {"version": "0.8"},
    {"version": "0.7"}
  ]
}

未嵌入任务

验证注解语法：检查注解 key 和 value 格式
检查 PipelineRun：确保 taskRef.name 与注解中的任务名称一致
查看 PAC controller 日志，查找嵌入错误

下一步

维护流水线代码 - 流水线定义指南
高级仓库配置 - Repository CR 高级设置
管理 PipelineRuns - PipelineRun 管理
常见问题 - 故障排查指南

#PAC 解析器

#目录

#前提条件

#关于 PAC 解析器

#支持的来源

#官方文档

#PAC 解析器的工作原理

#解析器工作流

#详细示例：逐步解析

#第 1 步：原始 PipelineRun 定义

#第 2 步：PAC Controller 处理注解

#第 3 步：PAC 将任务嵌入到 PipelineRun 中

#第 4 步：在 Kubernetes 中创建 PipelineRun

#解析时机

#验证任务解析

#使用本地任务

#内联任务定义（taskSpec）

#引用仓库中的任务文件

#何时使用本地任务

#使用远程任务注解

#来自 Tekton Hub 的远程任务

#来自 HTTP URL 的远程任务

#多个任务注解

#任务列表语法

#任务版本指定

#自定义 Hub URL

#使用远程流水线注解

#组合远程任务和流水线

#与 Resolver 语法的比较

#使用 PAC 注解（推荐）

#使用 Resolver 语法

#故障排查

#未找到任务

#任务解析失败

#未嵌入任务

#下一步

PAC 解析器

目录

前提条件

关于 PAC 解析器

支持的来源

官方文档

PAC 解析器的工作原理

解析器工作流

详细示例：逐步解析

第 1 步：原始 PipelineRun 定义

第 2 步：PAC Controller 处理注解

第 3 步：PAC 将任务嵌入到 PipelineRun 中

第 4 步：在 Kubernetes 中创建 PipelineRun

解析时机

验证任务解析

使用本地任务

内联任务定义（taskSpec）

引用仓库中的任务文件

何时使用本地任务

使用远程任务注解

来自 Tekton Hub 的远程任务

来自 HTTP URL 的远程任务

多个任务注解

任务列表语法

任务版本指定

自定义 Hub URL

使用远程流水线注解

组合远程任务和流水线

与 Resolver 语法的比较

使用 PAC 注解（推荐）

使用 Resolver 语法

故障排查

未找到任务

任务解析失败

未嵌入任务

下一步