配置 GitHub Repository
本指南将 GitHub 仓库与 PAC 端到端连接起来:选择集成模式、准备凭据、创建 Repository 资源,以及注册 webhook。
PAC 支持两种与 GitHub 集成的方式:
- GitHub App — 由管理员在 GitHub 组织(或用户)上一次性安装一个 GitHub App。之后,属于该安装的每个仓库都会通过仅包含 URL 的
Repository资源进行表示;无需为每个仓库单独配置 token 或 webhook。 - Webhook — 为每个仓库分别配置 Personal Access Token 和 webhook。当你不是 GitHub 组织所有者,或无法安装 App 时,这种方式更合适。
对于同一个 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:在 GitHub 中注册 webhook步骤 5:添加 PipelineRun 并触发验证故障排除下一步前提条件
- 已部署并暴露 PAC 组件;请参见 管理 PAC 组件。
- PAC webhook URL;请参见 获取 PAC Webhook URL。
- 具备 GitHub 仓库的管理员访问权限(用于添加 webhook),或 GitHub 组织的管理员访问权限(用于安装 App)。
- 一个目标 Kubernetes 命名空间,
Repository资源及其PipelineRuns 将在其中运行。 - 具备对该命名空间的
kubectl访问权限。 - 如果使用
tkn pac bootstrap,则需要安装了pac插件的tknCLI;请参见 tkn pac 命令参考。
选择集成模式
当你管理 GitHub 组织并计划接入多个仓库时,请使用 GitHub App 模式。对于一次性仓库、组织外的仓库,或无法安装 App 的情况,请使用 Webhook 模式。
集成模式 1:GitHub App
工作原理
安装在 GitHub 组织或用户上的 GitHub App 会将安装范围内每个仓库的事件发送给 PAC 控制器。PAC 代表该 App 向 GitHub 进行身份验证。Kubernetes 侧的凭据(App ID、private key、webhook secret)保存在 PAC 命名空间中的一个集群级 Secret 里;你无需在用户命名空间中放置任何每仓库凭据。
步骤 1(管理员):创建并安装 GitHub App
此步骤由集群管理员执行,每个集群只需一次。
选项 A:使用 tkn pac bootstrap
tkn pac bootstrap 会引导完成 GitHub App 的创建,并将生成的凭据存储到集群 Secret 中:
按照提示操作。该命令会创建 App、生成 private key,并在 PAC 命名空间中创建 pipelines-as-code-secret Secret。
选项 B:手动创建 GitHub App
-
前往 GitHub → Settings → Developer settings → GitHub Apps,然后点击 New GitHub App。
-
填写表单:
- GitHub App name:任意描述性名称,例如
Alauda DevOps 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、private key 和 webhook secret。将 <pac-namespace>(默认值 tekton-pipelines)、<app-id>、<webhook-secret> 和 <path-to-private-key> 替换为实际值:
PAC 会在每次接收到事件时读取该 Secret。无需重启控制器。
步骤 3(用户):创建 Repository 资源
当 App 安装到 GitHub 仓库后,普通用户即可在其命名空间中创建一个最小化的 Repository 资源。只需要仓库 URL;无需 git_provider 块。
应用它:
验证:
示例输出:
步骤 4(用户):添加 PipelineRun 并触发
在仓库的 .tekton/ 目录下添加一个 PipelineRun 清单并推送。PAC 会捕获该事件并在该命名空间中创建一个 PipelineRun。有关文件布局和注解语法,请参见 在 Git 中定义 PipelineRun;有关 PAC 响应的 Git 操作,请参见 触发流水线。
集成模式 2:Webhook
工作原理
在单个 GitHub 仓库上直接配置 Personal Access Token 和 webhook。PAC 使用该 token 读取仓库元数据并发布 commit status;webhook secret 在 GitHub 与集群之间共享,以便 PAC 验证每个事件的来源。
步骤 1:创建 Personal Access Token
按照 为 PAC 创建 Git Secret 中的说明,为 GitHub 配置所需的权限范围。简而言之,带有 repo 范围(仅公共仓库可使用 public_repo)的经典 Personal Access Token 即可。
步骤 2:创建 Kubernetes Secret
创建一个同时包含 Git 访问令牌和 webhook secret 的 Secret。操作步骤见 为 PAC 创建 Git Secret。
在本指南后续内容中,该 Secret 名为 github-webhook-config。
步骤 3:创建 Repository 资源
在 Repository 中引用该 Secret:
应用它:
步骤 4:在 GitHub 中注册 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 和 触发流水线。
验证
当 Git 事件到达后,PAC 会在 Repository 所在的命名空间中创建一个 PipelineRun。请确认:
PAC 控制器日志会显示该事件正在被处理:
对于状态上报,GitHub 会显示:
- 在 App 模式下:提交上的一个 Check Run,包含详细的步骤输出。
- 在 Webhook 模式下:一个指向集群的 commit status。
故障排除
完整的故障排除矩阵请参见 常见问题。
下一步
- 在 Git 中定义 PipelineRun — 在
.tekton/下定义并演进流水线。 - 触发流水线 — 通过 push、pull request 和评论驱动触发。
- 高级 Repository 配置 — 并发、参数、自定义设置。
- 配置自定义证书 — 适用于带有私有 CA 的 GitHub Enterprise。