配置 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 资源,这两种模式是互斥的。

前提条件

  • 已部署并暴露 PAC 组件;请参见 管理 PAC 组件。
  • PAC webhook URL;请参见 获取 PAC Webhook URL。
  • 具备 GitHub 仓库的管理员访问权限(用于添加 webhook),或 GitHub 组织的管理员访问权限(用于安装 App)。
  • 一个目标 Kubernetes 命名空间,Repository 资源及其 PipelineRuns 将在其中运行。
  • 具备对该命名空间的 kubectl 访问权限。
  • 如果使用 tkn pac bootstrap,则需要安装了 pac 插件的 tkn CLI;请参见 tkn pac 命令参考。

选择集成模式

GitHub AppWebhook
一次性设置范围每个组织或用户每个仓库
安装者管理员仓库维护者
每仓库 Secret不需要需要
每仓库 webhook不需要需要
状态上报GitHub Checks APIcommit status
可与 GitHub Enterprise 配合使用是是

当你管理 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 中:

tkn pac bootstrap

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

选项 B:手动创建 GitHub App

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

  2. 填写表单:

    • GitHub App name:任意描述性名称,例如 Alauda DevOps 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、private key 和 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。无需重启控制器。

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

当 App 安装到 GitHub 仓库后,普通用户即可在其命名空间中创建一个最小化的 Repository 资源。只需要仓库 URL;无需 git_provider 块。

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

应用它:

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 响应的 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:

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

应用它:

kubectl apply -f repository.yaml

步骤 4:在 GitHub 中注册 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 和 触发流水线。

验证

当 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 模式下:一个指向集群的 commit status。

故障排除

症状首先检查
webhook 投递失败并显示 connection refusedPAC webhook URL 是否可从 GitHub 访问。请参见 获取 PAC Webhook URL。
webhook 投递返回 401 或 403GitHub 中配置的 webhook.secret 是否与 Kubernetes Secret 中的值一致。
推送时未创建 PipelineRun.tekton/ 下是否存在 PipelineRun 清单,以及其 on-target-branch / on-event 注解是否与该事件匹配。请参见 在 Git 中定义 PipelineRun。
状态检查未回传token 范围是否包含 repo(Webhook 模式),或者 App 权限是否包含 Checks: Read & Write(App 模式)。

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

下一步