#配置 GitHub Repository

本指南将 GitHub repository 与 PAC 端到端连接起来：选择集成模式、准备凭证、创建 Repository 资源，以及注册 webhook。

PAC 支持两种与 GitHub 集成的方式：

• GitHub App — 由管理员在 GitHub organization（或 user）上一次性安装一个 GitHub App。之后，属于该 installation 的每个 repository 都通过仅包含 URL 的 Repository 资源来表示；无需为每个 repository 配置 token 或 webhook，因为 App 负责 webhook 投递。
• Webhook — 为每个 repository 配置 Personal Access Token 和 webhook。当你不拥有 GitHub organization，或无法安装 App 时适用。当启用自动 webhook 注册时，webhook registration controller 会为你创建或更新 repository webhook。

这两种模式对同一个 Repository 资源是互斥的。

#前提条件

• 已部署并公开 PAC 组件；请参见 管理 PAC 组件。
• PAC webhook URL 已记录在 pipelines-as-code-info.data.controller-url 中。有关设置和验证，请参见 获取 PAC Webhook URL。
• 具有 GitHub repository 的管理员访问权限、具有管理 repository webhooks 权限的 token，或者可访问 GitHub organization 以安装 App。
• 一个目标 Kubernetes namespace，用于存放 Repository 资源及其 PipelineRuns。
• 对该 namespace 的 kubectl 访问权限。
• 如果使用 tkn pac bootstrap，需要已安装 pac plugin 的 tkn CLI；请参见 tkn pac 命令参考。

#选择集成模式

当你管理 GitHub organization，并计划接入多个 repository 时，请使用 GitHub App 模式。当你只需要接入单个 repository、接入组织外的 repository，或无法安装 App 时，请使用 Webhook 模式。

#集成模式 1：GitHub App

#工作原理

安装在 GitHub organization 或 user 上的 GitHub App，会将该 installation 中每个 repository 的事件发送到 PAC controller。PAC 代表该 App 向 GitHub 进行身份验证。Kubernetes 侧的凭证（App ID、private key、webhook secret）存放在 PAC namespace 中一个集群级 Secret 里；你不需要在 user namespace 中放置任何按 repository 区分的凭证。

#步骤 1（管理员）：创建并安装 GitHub App

此步骤由 cluster administrator 每个 cluster 执行一次。

#选项 A：使用 tkn pac bootstrap

tkn pac bootstrap 会引导你完成 GitHub App 的创建，并将生成的凭证保存到 cluster Secret 中：

tkn pac bootstrap

按照提示操作。该命令会创建 App、生成 private key，并在 PAC namespace 中创建 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：

   Permission	Access
   Checks	Read & Write
   Contents	Read & Write
   Issues	Read & Write
   Metadata	Read-only
   Pull requests	Read & Write

4. 设置 Organization permissions：

   Permission	Access
   Members	Read-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 处理的 organization 或 user 以及 repository。

#步骤 2（管理员）：将 GitHub App 凭证存储到 Kubernetes

在 PAC namespace 中创建一个 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。无需重启 controller。

#步骤 3（用户）：创建 Repository 资源

当 App 已安装到 GitHub repository 后，普通用户可在自己的 namespace 中创建一个最小化的 Repository 资源。在 GitHub App 模式下，只需要 repository 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>

应用它：

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

在 repository 的 .tekton/ 下添加一个 PipelineRun 清单并推送。PAC 会捕获该事件，并在该 namespace 中创建一个 PipelineRun。有关文件布局和注解语法，请参见 在 Git 中定义 PipelineRun；有关自动触发和基于评论的触发，请参见 触发 PAC Pipelines。

#集成模式 2：Webhook

#工作原理

Personal Access Token 和 webhook 直接配置在单个 GitHub repository 上。PAC 使用该 token 读取 repository 元数据并发布 commit status；webhook secret 由 GitHub 和 cluster 共享，因此 PAC 可以验证每个事件的来源。

#步骤 1：创建 Personal Access Token

请按照 为 PAC 创建 Git Secret 中针对 GitHub 所需的 Repository 级 token 权限进行操作。PAC 使用该 token 读取 repository 数据并报告 pipeline 结果。当配置了集中式 webhook 注册凭证时，该 token 不需要 webhook 管理权限。

对于自动 webhook 注册，请配置匹配的集中式凭证：经典 PAT 使用 admin:repo_hook，fine-grained PAT 使用目标 repository 的 Webhooks 写权限。请参见 集中式 webhook 注册 token。

#步骤 2：创建 Kubernetes Secret

创建一个同时包含 Git access token 和 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:
    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 registration controller 会监视它并注册 GitHub repository 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。controller 会创建或更新一个 GitHub web hook，包含以下内容：

• Payload URL：公开的 PAC webhook URL
• Content type：application/json
• Secret：spec.git_provider.webhook_secret 引用的 webhook.secret 值
• Events：commit comments、issue comments、pull requests 和 pushes
• SSL verification：默认启用

controller 会将 GitHub hook ID 记录在 pac.tekton.alauda.io/webhook-managed-ref 中。如果 PAC webhook URL 之后发生变化，controller 会通过 ID 更新已记录的 hook，而不是为同一个 repository 创建重复的 hook。

若要将某个 Repository 排除在自动 webhook 注册之外，请在 Repository 的 metadata 中添加以下 label：

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

#手动回退

如果无法使用自动注册，或者它被禁用，请手动注册 webhook：

1. 打开 GitHub repository，然后依次进入 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 模式相同：在 repository 的 .tekton/ 下添加一个 PipelineRun。请参见 在 Git 中定义 PipelineRun 和 触发 PAC Pipelines。

#验证

当 Git 事件到达后，PAC 会在 Repository 所在的 namespace 中创建一个 PipelineRun。请确认：

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

PAC controller 日志会显示事件正在被处理：

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

对于状态报告，GitHub 会显示：

• 在 App 模式下：commit 上的一个 Check Run，包含详细的 step 输出。
• 在 Webhook 模式下：一个指向 cluster 的 commit status。

#故障排查

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

#后续步骤

• 在 Git 中定义 PipelineRun — 在 .tekton/ 下定义和演进 pipeline。
• 触发 PAC Pipelines — 自动事件和评论命令。
• 高级 Repository 配置 — 并发、参数、自定义设置。
• 配置自定义证书 — 适用于带有私有 CA 的 GitHub Enterprise。