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 控制器
获取流水线：PAC 控制器从你的 Git 仓库中获取 PipelineRun 定义
识别注解：PAC 控制器扫描注解中的 resolver 指令：
- pipelinesascode.tekton.dev/task: "task-name"
- pipelinesascode.tekton.dev/task-1: "task-name"
- pipelinesascode.tekton.dev/pipeline: "pipeline-name"
任务解析：针对每个任务注解：
- PAC 控制器查询 Tekton Hub API（或已配置的 Hub URL）
- 获取任务定义（YAML）
- 验证任务结构
任务嵌入：PAC 将解析后的任务定义嵌入到 PipelineRun 中：
- PAC 将 taskRef 转换为 taskSpec，并把任务定义以内联方式嵌入到每个任务条目中
- 嵌入的任务成为 PipelineRun 定义的一部分，因此它不需要作为集群中的独立 Task 资源存在
创建 PipelineRun：PAC 在 Kubernetes 中创建包含嵌入任务的最终 PipelineRun
执行：Tekton Pipeline 控制器接管该 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 控制器处理注解

当发生 push 事件时，PAC 控制器会：

从 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"），以保证可复现性和稳定性
开发/测试：使用最新版本（不带版本后缀），以自动获取新功能和错误修复
版本固定：在生产环境中始终固定到特定版本，以避免 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 converts taskRef to taskSpec and embeds the task definition
      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
      # Task definition is embedded as 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"

解析时机

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

任务是在流水线定义阶段解析，而不是在执行阶段
如果某个任务无法解析，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 控制器日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i "task.*resolve"  # Replace <pac-namespace> with your actual namespace (default: 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"}

验证任务是否被正确引用：

# Check that taskRef.name matches the task name in annotations
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）

你可以使用 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: 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 以内联方式定义在 pipeline 中的每个任务内
无需外部解析——任务本身就是 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]"
    # Reference local tasks using relative paths
    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]"
    # Reference task from remote 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 documentation。

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

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"  # Uses latest

自定义 Hub URL

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

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    # For cluster-internal Hub in different namespace
    hub-url: "http://tekton-hub-api.<your-namespace>:8000/v1"
    
    # Or for external/public Hub
    hub-url: "https://api.hub.tekton.dev/v1"
    
    # Or for custom Hub instance
    hub-url: "https://custom-hub.example.com/v1"

注意：只有 PAC 控制器需要能够访问 Hub URL。如果使用集群内 Hub，请确保 PAC 控制器能够访问该 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]"
    # Reference remote pipeline from 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 控制器能够访问 Tekton Hub

# Test Hub connectivity from PAC controller pod
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

检查任务版本：确认指定版本存在

# Query Tekton Hub for available versions
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"}
  ]
}

任务未嵌入

验证注解语法：检查注解键和值的格式
检查 PipelineRun：确保 taskRef.name 与注解中的任务名称一致
查看 PAC 控制器日志，定位嵌入错误

下一步

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

#PAC 解析器

#目录

#前提条件

#关于 PAC 解析器

#支持的来源

#官方文档

#PAC 解析器的工作原理

#解析器工作流

#详细示例：逐步解析

#步骤 1：原始 PipelineRun 定义

#步骤 2：PAC 控制器处理注解

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

#步骤 4：在 Kubernetes 中创建 PipelineRun

#解析时机

#验证任务解析

#使用本地任务

#内联任务定义（taskSpec）

#引用仓库中的任务文件

#何时使用本地任务

#使用远程任务注解

#来自 Tekton Hub 的远程任务

#来自 HTTP URL 的远程任务

#多任务注解

#任务列表语法

#任务版本指定

#自定义 Hub URL

#使用远程流水线注解

#组合远程任务和流水线

#与 Resolver 语法的比较

#使用 PAC 注解（推荐）

#使用 Resolver 语法

#故障排查

#未找到任务

#任务解析失败

#任务未嵌入

#下一步

PAC 解析器

目录

前提条件

关于 PAC 解析器

支持的来源

官方文档

PAC 解析器的工作原理

解析器工作流

详细示例：逐步解析

步骤 1：原始 PipelineRun 定义

步骤 2：PAC 控制器处理注解

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

步骤 4：在 Kubernetes 中创建 PipelineRun

解析时机

验证任务解析

使用本地任务

内联任务定义（taskSpec）

引用仓库中的任务文件

何时使用本地任务

使用远程任务注解

来自 Tekton Hub 的远程任务

来自 HTTP URL 的远程任务

多任务注解

任务列表语法

任务版本指定

自定义 Hub URL

使用远程流水线注解

组合远程任务和流水线

与 Resolver 语法的比较

使用 PAC 注解（推荐）

使用 Resolver 语法

故障排查

未找到任务

任务解析失败

任务未嵌入

下一步