配置 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 权限的令牌,或具备在 GitHub 组织中安装 App 的访问权限。
  • 一个目标 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:

    权限访问权限
    Checks读取和写入
    Contents读取和写入
    Issues读取和写入
    Metadata只读
    Pull requests读取和写入
  4. 设置 Organization permissions:

    权限访问权限
    Members只读
  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 资源

在 GitHub 仓库上安装 App 后,普通用户可以在其命名空间中创建最小化的 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,请使用 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:

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。检查 Repository 注解和事件:

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
  • 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。

INFO

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

要排除某个 Repository,使其不进行自动 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。
    • Content type:application/json。
    • Secret:存储在 Kubernetes Secret 中的相同 webhook.secret 值。
    • SSL verification:启用(推荐)。
  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 Pipeline。

验证

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 模式)。

有关完整的故障排除矩阵,请参阅常见问题。

后续步骤