#核心概念

本页介绍 PAC 在 Tekton 之上引入的资源、运行时组件和触发模型。要快速了解整体概览和受众映射，请参见 介绍。

#架构

PAC 在集群中运行三个 controller，并对 Git 提供方传递的事件作出响应：

• PAC Webhook 是向 Git 提供方暴露的 HTTP 监听器。它会使用共享的 webhook secret 验证每个传入请求，并将已验证的 payload 转发给 controller。任何验证失败的内容都会在接触 Tekton 之前被丢弃。
• PAC Controller 负责处理“在该事件上应运行什么”的逻辑。它会查找匹配的 Repository 资源，获取事件所引用 ref 下的 .tekton/ 清单，通过触发注解对其进行过滤，展开变量，并创建 PipelineRun。
• PAC Watcher 跟踪 PAC 创建的 PipelineRun，并将其状态回报给 Git 提供方——根据提供方不同，回报形式可以是 GitHub Check Run、commit status 或 comment。

这三个组件都运行在 PAC namespace 中（默认值：tekton-pipelines），并由 Tekton Operator 根据 OpenShiftPipelinesAsCode CR 进行部署。

#Repository 资源

Repository 是你针对每个 Git repository 维护的唯一资源。它将一个 Git URL 绑定到一个 Kubernetes namespace：来自该 URL 的事件会在这个 namespace 中生成 PipelineRun，并且只会在这个 namespace 中生成。多个 Repository 资源可以指向同一个 Git URL，但必须位于不同的 namespace 中——这通常用于“每个环境一个 team namespace”的布局。

Repository 不包含任何 pipeline 定义。pipeline 定义保存在 Git repository 本身中，位于 .tekton/ 下。删除 Repository 只会停止 PAC 创建新的 PipelineRun；已经创建的运行会保留原样。

#关键 spec 字段

示例（通过 Webhook 的 GitLab）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.com/group/project
  git_provider:
    type: gitlab
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

在 GitHub App 模式下，整个 git_provider 块都会省略；PAC 使用集群级 App 凭据进行认证，因此不需要按 repository 配置 token 和 webhook secret。

#两种集成模式

Git 提供方有两种方式将事件传递给 PAC，而 Repository spec 会随着方式不同而改变。

• GitHub App 模式 — 在 GitHub organization 或 user 上一次性安装 GitHub App。该 App 在 organization 级别拥有 webhook 和凭据。安装覆盖范围内的每个 repository 都可以使用最小化的 Repository（只需 spec.url）接入。状态通过 GitHub Checks API 报告。仅适用于 GitHub。
• Webhook 模式 — 针对每个 repository 配置 Personal Access Token 和 webhook。Repository 引用一个 Kubernetes Secret，其中包含 token 和 webhook secret。状态以 commit status 形式报告。本文档涵盖 GitHub Webhook 模式和 GitLab Webhook 模式。

这两种模式在同一个 Repository 上互斥。各提供方的端到端流程请参见 指南。

#.tekton/ 目录约定

PAC 会从 Git repository 根目录下的 .tekton/ 目录读取 PipelineRun 清单。约定如下：

• 会扫描 .tekton/ 下任何 .yaml 或 .yml 文件。每个文件可以包含多个 PipelineRun，每个 repository 也可以包含多个文件。
• 清单会从事件触发时对应的 ref 读取——pull request 会读取源分支，push 会读取被推送的分支，tag push 会读取 tag 的 ref。
• 每个 PipelineRun 都会独立评估。单个事件可以根据匹配到的清单数量生成零个、一个或多个 PipelineRun。
• 适用标准 PipelineRun 结构；PAC 只是在其上添加 annotations 和变量。Task 可以是内联的（pipelineSpec）、引用集群中已有的 Pipeline（pipelineRef），或在提交时从 Tekton Hub 或远程 URL 解析。

#事件生命周期

有几个值得注意的特性：

• webhook 处的验证步骤是 fail-closed：签名无效的事件不会到达 controller、Repository controller，也不会进入集群。
• controller 会在创建任何 Kubernetes 对象之前完成过滤和变量展开，因此不匹配的事件不会生成 PipelineRun，除了日志行之外不会留下任何痕迹。
• 状态报告是异步的，并且会在 PipelineRun 状态变化时发生，包括完成和单个 step 失败（在提供方支持按 step 报告时）。

#触发模型

PipelineRun 清单通过 metadata.annotations 上的注解声明它们关心的事件。controller 会根据这些注解对事件和清单进行过滤。

#事件类型

#注解语法

一对简单的匹配器（on-event + on-target-branch）足以覆盖大多数场景。对于复合条件（“仅当 PR head 匹配 feature/* 且变更文件包含 api/**”），请改用 CEL expression：

annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" &&
    source_branch.startsWith("feature/") &&
    files.modified.exists(f, f.startsWith("api/"))

CEL 程序会接收 event、event_title、target_branch、source_branch、body、headers，以及一个包含 all、added、deleted、modified 和 renamed 列表的 files 对象。

完整的注解语法、更多 CEL 示例以及冲突解决规则，请参见 在 Git 中定义 PipelineRuns。

#变量与解析

在 PipelineRun 创建时，PAC 会基于事件 payload 展开一小组占位符。其值在创建后会固定，不会重新计算。

PAC 还可以在提交时内联 Task 和 Pipeline 清单——包括通过路径引用的本地文件、通过短名称引用的 Tekton Hub 资源，或远程 URL。解析器会在 PipelineRun 创建之前运行，因此生成的对象是自包含的。语法和支持的数据源请参见 PAC Resolver。

#状态报告

PAC 会通过三种通道将 PipelineRun 状态回报给 Git 提供方，并会根据提供方和集成模式自动选择：

• GitHub Checks API — 用于 GitHub App 模式。每个 PipelineRun 会显示为一个 Check Run，并带有按 step 输出以及附加到 commit 的“进行中 / 成功 / 失败”徽标。
• Commit statuses — 用于 GitHub Webhook 模式和 GitLab。会在 commit 上以及（在适用时）PR / MR 上发布一条简短状态。
• Comment — 对于失败情况，会在 PR / MR 上添加一条 comment，其中包含 PipelineRun 名称和指向集群的链接。具体格式取决于提供方。

这些状态报告中嵌入的集群侧 URL 可以通过 OpenShiftPipelinesAsCode 中的 custom-console-url-* 设置进行自定义；请参见 管理 PAC 组件。

#并发与取消

默认情况下，每个匹配事件都会立即创建其 PipelineRun。以下两个设置决定了该行为：

• Repository.spec.concurrency_limit 限制该 repository 中可并行运行的 PipelineRun 数量。超出的运行会排队，并在较早的运行完成后启动。
• PipelineRun 上的 pipelinesascode.tekton.dev/cancel-in-progress 注解会指示 PAC 在启动新运行之前，取消与相同事件组匹配的任何旧运行（例如同一个 PR）——当针对 PR 的新 push 应使先前的 CI build 失效时，这非常有用。

这些只是基本控制项；高级字段的完整集合请参见 高级 Repository 配置。

#安全与访问

• webhook payload 会根据 webhook.secret 进行验证；该值只保存在集群 Secret 中，不会出现在事件或日志中。
• Git 访问令牌（Webhook 模式）或 GitHub App 私钥（App 模式）也会存储为 Kubernetes Secret；令牌不会出现在 PipelineRun spec 中。
• Repository 是命名空间级资源；标准 Kubernetes RBAC 决定谁可以创建或修改它。只授予“read repositories”而不授予“create”，可以让用户查看已集成内容但不能修改它。
• 向 Git 提供方回报状态时，始终使用集群侧身份（App 模式下为 App，Webhook 模式下为所配置的 token）。不会将单个事件发送者的权限进行委派。

#下一步

• 快速开始 — 端到端最小示例。
• 指南 — 按 Git 提供方提供完整的配置流程。
• 在 Git 中定义 PipelineRuns — 注解语法和 PipelineRun 布局。
• 常见问题 — 故障排查。