配置 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 资源,这两种模式不能同时使用。

前提条件

  • 已部署并公开 PAC 组件;请参阅 管理 PAC 组件。
  • PAC webhook URL 已记录在 pipelines-as-code-info.data.controller-url 中。有关设置和验证,请参阅获取 PAC Webhook URL。
  • 具备 GitHub 仓库的管理员访问权限、拥有管理仓库 webhook 权限的令牌,或具备可安装 App 的 GitHub 组织访问权限。
  • 一个目标 Kubernetes 命名空间,用于存放 Repository 资源及其 PipelineRun。
  • 对该命名空间具有 kubectl 访问权限。
  • 如果使用 tkn pac bootstrap,请安装带有 pac 插件的 tkn CLI;请参阅 tkn pac 命令参考。

选择集成模式

GitHub AppWebhook
一次性设置范围每个组织或用户每个仓库
安装者管理员仓库维护者
每个仓库的 Secret不需要需要
每个仓库的 webhook不需要需要
状态报告GitHub Checks API提交状态
是否适用于 GitHub Enterprise是是

如果您管理 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 中:

tkn pac bootstrap

按照提示操作。该命令会创建 App、生成私钥,并在 PAC 命名空间中创建 pipelines-as-code-secret Secret。

选项 B:手动创建 GitHub App

  1. 转到 GitHub → Settings → Developer settings → GitHub Apps,然后点击 New GitHub App。

  2. 填写表单:

    • GitHub App name:任意描述性名称,例如 Alauda Container Platform Pipelines。
    • Homepage URL:任意 URL,例如平台控制台 URL。
    • Webhook URL:前提条件中提供的 PAC webhook URL。
    • Webhook secret:任意随机字符串。请保存该字符串;下一步需要将其存储在 Kubernetes 中。
  3. 设置 Repository permissions:

    PermissionAccess
    ChecksRead & Write
    ContentsRead & Write
    IssuesRead & Write
    MetadataRead-only
    Pull requestsRead & Write
  4. 设置 Organization permissions:

    PermissionAccess
    MembersRead-only
  5. 订阅以下事件:Check run、Check suite、Commit comment、Issue comment、Pull request、Push。

  6. 点击 Create GitHub App。

  7. 在 App 详细信息页面中,记下 App ID。

  8. 在 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>:

kubectl -n <pac-namespace> create secret generic pipelines-as-code-secret \
  --from-literal github-application-id='<app-id>' \
  --from-literal webhook.secret='<webhook-secret>' \
  --from-file github-private-key='<path-to-private-key>'

PAC 会在每次收到事件时读取此 Secret。无需重启 controller。

步骤 3(用户):创建 Repository 资源

将 App 安装到 GitHub 仓库后,普通用户可以在其命名空间中创建一个最小化的 Repository 资源。在 GitHub App 模式下,只需提供仓库 URL,因为 App 级别的 webhook 会将事件发送到 PAC。

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>
INFO

此仅包含 spec.url 的结构适用于 GitHub App 模式。自动 webhook 注册 controller 不使用此结构。对于 GitHub Webhook 模式,请按照下一节中的说明设置 spec.git_provider.type: github。

应用该资源:

kubectl apply -f repository.yaml

验证:

kubectl get repositories -n project-pipelines

示例输出:

NAME      URL                                  SUCCEEDED   REASON   STARTTIME   COMPLETIONTIME
my-repo   https://github.com/owner/repo

步骤 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,请为经典 PAT 配置包含 admin:repo_hook 的匹配集中式凭证;对于细粒度 PAT,则配置目标仓库的 Webhooks 写入权限。请参阅集中式 webhook 注册令牌。

步骤 2:创建 Kubernetes Secret

创建一个同时包含 Git 访问令牌和 webhook 密钥的 Secret。有关操作步骤,请参阅为 PAC 创建 Git Secret。

在本指南的其余部分中,该 Secret 名称为 github-webhook-config。

步骤 3:创建 Repository 资源

在 Repository 中引用该 Secret:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>
  git_provider:
    type: github
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

应用它:

kubectl apply -f repository.yaml

对于 GitHub Enterprise,将 git_provider.url 设置为 Enterprise API URL:

spec:
  url: https://github.example.com/<owner>/<repo>
  git_provider:
    type: github
    url: https://github.example.com/api/v3
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

步骤 4:验证 webhook 自动注册

创建 Repository 后,webhook 注册控制器会监视它,并注册 GitHub 仓库 webhook。检查仓库注解和事件:

kubectl describe repository my-repo -n project-pipelines
kubectl get repository my-repo -n project-pipelines \
  -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-status}'

预期状态为 Registered。控制器会创建或更新 GitHub web hook,其中包括:

  • Payload URL:PAC 公共 webhook URL
  • 内容类型:application/json
  • Secret:由 spec.git_provider.webhook_secret 引用的 webhook.secret 值
  • 事件:提交评论、议题评论、拉取请求和推送
  • SSL 验证:默认启用

自动注册由 tektoncd-enhancement-controller 配置。有关 pac-webhook-registration.* 设置(包括提供程序端 TLS 验证),请参阅通过 TektonConfig 配置增强功能。如果 GitHub Enterprise API 使用私有 CA,还请按照配置自定义证书 配置控制器信任设置。

控制器会在 pac.tekton.alauda.io/webhook-managed-ref 中记录 GitHub hook ID。如果 PAC webhook URL 后续发生变化,控制器会根据 ID 更新已记录的 hook,而不是为同一仓库创建重复的 hook。

INFO

控制器会优先使用来自 spec.git_provider.secret 的令牌。请将该仓库本地令牌限定为 PAC 的正常访问范围。如果该令牌缺失或没有 webhook 管理权限,控制器可以使用 webhook 注册控制器命名空间中一个匹配的带标签凭证 Secret。对于经典 PAT,集中式 GitHub 凭证需要 admin:repo_hook;对于细粒度 PAT,则需要目标仓库的 Webhooks 写入权限。请参阅为 PAC 创建 Git Secret。

要排除某个仓库,使其不进行 webhook 自动注册,请将此标签添加到 Repository 元数据:

metadata:
  labels:
    pac.tekton.alauda.io/webhook-registration-disabled: "true"

手动回退

如果自动注册已禁用或无法使用,请手动注册 webhook:

  1. 打开 GitHub 仓库,然后选择 Settings → Webhooks → Add webhook。
  2. 填写表单:
    • Payload URL:先决条件中提供的 PAC webhook URL。
    • 内容类型:application/json。
    • Secret:存储在 Kubernetes Secret 中的相同 webhook.secret 值。
    • SSL 验证:启用(推荐)。
  3. 在 Which events would you like to trigger this webhook? 下,选择 Let me select individual events,然后选中:
    • Commit comments
    • Issue comments
    • Pull requests
    • Pushes
  4. 单击 Add webhook。

GitHub 会立即发送一个 ping 事件。webhook 条目上的绿色勾号表示 PAC 已接受该事件。

步骤 5:添加 PipelineRun 并触发它

与 App 模式相同:在仓库的 .tekton/ 下添加 PipelineRun。请参阅在 Git 中定义 PipelineRun和触发 PAC Pipelines。

验证

Git 事件到达后,PAC 会在 Repository 的命名空间中创建一个 PipelineRun。请确认:

kubectl get pipelineruns -n project-pipelines \
  -l pipelinesascode.tekton.dev/repository=my-repo

PAC 控制器日志会显示正在处理该事件:

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

对于状态报告,GitHub 会显示:

  • 在 App 模式下:提交上的 Check Run,其中包含详细的步骤输出。
  • 在 Webhook 模式下:链接回集群的提交状态。

故障排除

症状首先检查
Webhook 投递失败并显示 connection refusedPAC webhook URL 可从 GitHub 访问。请参阅获取 PAC Webhook URL。
Webhook 投递返回 401 或 403在 GitHub 中配置的 webhook.secret 与 Kubernetes Secret 中的值一致。
仓库注解 webhook-registration-status=Failed运行 kubectl describe repository <name> -n <ns> 并检查 pac.tekton.alauda.io/webhook-registration-reason。常见原因包括缺少令牌、令牌权限不足、GitHub Enterprise API URL 错误或证书不受信任。
推送时未创建 PipelineRun.tekton/ 下存在 PipelineRun 清单,并且其 on-target-branch / on-event 注解与事件匹配。请参阅在 Git 中定义 PipelineRun。
未报告状态检查令牌范围包括 repo(Webhook 模式),或 App 权限包括 Checks: Read & Write(App 模式)。

如需查看完整的故障排除矩阵,请参阅常见问题。

后续步骤