配置 GitHub 仓库
本指南端到端地将 GitHub 仓库连接到 PAC:选择集成模式、准备凭证、创建 Repository 资源并注册 webhook。
PAC 支持两种与 GitHub 集成的方式:
- GitHub App — 管理员只需在 GitHub 组织(或用户)上安装一次 GitHub App。属于该安装范围的每个仓库随后都通过仅包含 URL 的
Repository资源表示;无需配置每个仓库的令牌或 webhook,因为 App 负责 webhook 传递。 - Webhook — 为每个仓库配置 Personal Access Token 和 webhook。适用于您不拥有 GitHub 组织,或无法安装 App 的情况。启用自动 webhook 注册后,webhook 注册控制器会为您创建或更新仓库 webhook。
对于给定的 Repository 资源,这两种模式不能同时使用。
目录
先决条件选择集成模式集成模式 1:GitHub App工作原理步骤 1(管理员):创建并安装 GitHub App选项 A:使用tkn pac bootstrap选项 B:手动创建 GitHub App步骤 2(管理员):在 Kubernetes 中存储 GitHub App 凭证步骤 3(用户):创建 Repository 资源步骤 4(用户):添加 PipelineRun 并触发它集成模式 2:Webhook工作原理步骤 1:创建 Personal Access Token步骤 2:创建 Kubernetes Secret步骤 3:创建 Repository 资源步骤 4:验证自动 webhook 注册手动备用方案步骤 5:添加 PipelineRun 并触发它验证故障排除后续步骤先决条件
- 已部署并公开 PAC 组件;请参阅管理 PAC 组件。
- PAC webhook URL 已记录在
pipelines-as-code-info.data.controller-url中。有关设置和验证,请参阅获取 PAC Webhook URL。 - 具备 GitHub 仓库的管理员访问权限、具有管理仓库 webhook 权限的令牌,或具备在 GitHub 组织中安装 App 的访问权限。
- 一个目标 Kubernetes 命名空间,
Repository资源及其PipelineRun将在其中创建。 - 对该命名空间的
kubectl访问权限。 - 如果使用
tkn pac bootstrap,请安装带有pac插件的tknCLI;请参阅 tkn pac 命令参考。
选择集成模式
当您管理 GitHub 组织并计划接入多个仓库时,请使用 GitHub App 模式。对于一次性仓库、组织外部的仓库,或无法安装 App 的情况,请使用 Webhook 模式。
集成模式 1:GitHub App
工作原理
安装在 GitHub 组织或用户上的 GitHub App 会向 PAC controller 发送该安装涵盖的每个仓库的事件。PAC 代表 App 向 GitHub 进行身份验证。Kubernetes 端的凭证(App ID、私钥、webhook secret)存储在 PAC 命名空间中集群范围的 Secret 内;无需在用户命名空间中放置任何每个仓库的凭证。
步骤 1(管理员):创建并安装 GitHub App
此步骤由集群管理员执行,每个集群只需执行一次。
选项 A:使用 tkn pac bootstrap
tkn pac bootstrap 会引导您完成 GitHub App 的创建,并将生成的凭证存储在集群 Secret 中:
按照提示操作。该命令会创建 App、生成私钥,并在 PAC 命名空间中创建 pipelines-as-code-secret Secret。
选项 B:手动创建 GitHub App
-
转到 GitHub → Settings → Developer settings → GitHub Apps,然后单击 New GitHub App。
-
填写表单:
- GitHub App name:任意描述性名称,例如
Alauda Container Platform Pipelines。 - Homepage URL:任意 URL,例如平台控制台 URL。
- Webhook URL:前提条件中记录的 PAC webhook URL。
- Webhook secret:任意随机字符串。请保存该字符串;下一步将在 Kubernetes 中存储它。
- GitHub App name:任意描述性名称,例如
-
设置 Repository permissions:
-
设置 Organization permissions:
-
订阅以下事件:Check run、Check suite、Commit comment、Issue comment、Pull request、Push。
-
单击 Create GitHub App。
-
在 App 详细信息页面上记下 App ID。
-
在 Private keys 中,单击 Generate a private key,并保存下载的
.pem文件。
安装 App:在 App 页面中,单击 Install App,然后选择要让 PAC 处理的组织或用户以及仓库。
步骤 2(管理员):在 Kubernetes 中存储 GitHub App 凭证
在 PAC 命名空间中创建一个 Secret,用于存储 App ID、私钥和 webhook secret。替换 <pac-namespace>(默认值为 tekton-pipelines)、<app-id>、<webhook-secret> 和 <path-to-private-key>:
PAC 会在每次收到事件时读取此 Secret。无需重启 controller。
步骤 3(用户):创建 Repository 资源
在 GitHub 仓库上安装 App 后,普通用户可以在其命名空间中创建最小化的 Repository 资源。在 GitHub App 模式下,只需提供仓库 URL,因为 App 级别的 webhook 会将事件传送到 PAC。
此仅包含 spec.url 的形式适用于 GitHub App 模式。自动 webhook 注册 controller 不使用此形式。对于 GitHub Webhook 模式,请按照下一节所示设置 spec.git_provider.type: github。
应用该资源:
验证:
示例输出:
步骤 4(用户):添加 PipelineRun 并触发它
在仓库的 .tekton/ 下添加 PipelineRun 清单并推送。PAC 会捕获该事件,并在命名空间中创建 PipelineRun。有关文件布局和注解语法,请参阅在 Git 中定义 PipelineRun;有关自动触发器和基于评论的触发器,请参阅触发 PAC Pipeline。
集成模式 2:Webhook
工作原理
在单个 GitHub 仓库上直接配置 Personal Access Token 和 webhook。PAC 使用该令牌读取仓库元数据并发布提交状态;webhook 密钥由 GitHub 和集群共享,因此 PAC 可以验证每个事件的来源。
步骤 1:创建 Personal Access Token
请按照为 PAC 创建 Git Secret 操作,配置 GitHub 所需的仓库本地令牌权限。PAC 使用此令牌读取仓库数据并报告流水线结果。当配置了集中式 webhook 注册凭证时,此令牌不需要 webhook 管理权限。
要自动注册 webhook,请使用 admin:repo_hook 为 classic PAT 配置匹配的集中式凭证;如果使用 fine-grained PAT,则为目标仓库配置 Webhooks 写入权限。请参阅集中式 webhook 注册令牌。
步骤 2:创建 Kubernetes Secret
创建一个同时包含 Git 访问令牌和 webhook 密钥的 Secret。有关操作步骤,请参阅为 PAC 创建 Git Secret。
在本指南的其余部分中,该 Secret 名为 github-webhook-config。
步骤 3:创建 Repository 资源
在 Repository 中引用该 Secret:
应用该资源:
对于 GitHub Enterprise,将 git_provider.url 设置为 Enterprise API URL:
步骤 4:验证自动 webhook 注册
创建 Repository 后,webhook 注册控制器会监视该资源,并注册 GitHub 仓库 webhook。检查 Repository 注解和事件:
预期状态为 Registered。控制器会创建或更新 GitHub web hook,其中包含:
- Payload URL:公开的 PAC webhook URL
- Content type:
application/json - Secret:由
spec.git_provider.webhook_secret引用的webhook.secret值 - Events:提交评论、议题评论、拉取请求和推送
- SSL verification:默认启用
控制器会在 pac.tekton.alauda.io/webhook-managed-ref 中记录 GitHub hook ID。如果 PAC webhook URL 后续发生变化,控制器会通过 ID 更新已记录的 hook,而不是为同一仓库创建重复的 hook。
控制器首先使用来自 spec.git_provider.secret 的令牌。请将该仓库本地令牌限制为 PAC 的常规访问范围。如果该令牌缺失或没有 webhook 管理权限,控制器可以使用 webhook 注册控制器命名空间中一个匹配的带标签凭证 Secret。对于 classic PAT,集中式 GitHub 凭证需要 admin:repo_hook;对于 fine-grained PAT,则需要目标仓库的 Webhooks 写入权限。请参阅为 PAC 创建 Git Secret。
要排除某个 Repository,使其不进行自动 webhook 注册,请将以下标签添加到 Repository 元数据中:
手动备用方案
如果自动注册已禁用或无法使用,请手动注册 webhook:
- 打开 GitHub 仓库,然后选择 Settings → Webhooks → Add webhook。
- 填写表单:
- Payload URL:先决条件中提供的 PAC webhook URL。
- Content type:
application/json。 - Secret:存储在 Kubernetes Secret 中的相同
webhook.secret值。 - SSL verification:启用(推荐)。
- 在 Which events would you like to trigger this webhook? 下,选择 Let me select individual events,然后勾选:
- Commit comments
- Issue comments
- Pull requests
- Pushes
- 单击 Add webhook。
GitHub 会立即发送一个 ping 事件。webhook 条目旁的绿色勾号表示 PAC 已接受该事件。
步骤 5:添加 PipelineRun 并触发它
与 App 模式相同:在仓库的 .tekton/ 下添加 PipelineRun。请参阅在 Git 中定义 PipelineRun和触发 PAC Pipeline。
验证
Git 事件到达后,PAC 会在 Repository 的命名空间中创建一个 PipelineRun。请确认:
PAC 控制器日志显示事件正在处理:
对于状态报告,GitHub 会显示:
- 在 App 模式下:提交上的 Check Run,其中包含详细的步骤输出。
- 在 Webhook 模式下:链接回集群的提交状态。
故障排除
有关完整的故障排除矩阵,请参阅常见问题。
后续步骤
- 在 Git 中定义 PipelineRun — 在
.tekton/下定义和演进流水线。 - 触发 PAC 流水线 — 自动事件和评论命令。
- 高级仓库配置 — 并发、参数和自定义设置。
- 配置自定义证书 — 用于具有私有 CA 的 GitHub Enterprise。