#配置 GitHub 仓库

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

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

• GitHub App — 由管理员在 GitHub organization（或 user）上一次性安装一个 GitHub App。随后，属于该安装的每个仓库都会通过仅包含 URL 的 Repository 资源来表示；无需为每个仓库单独配置 token 或 webhook。
• Webhook — 为每个仓库分别配置 Personal Access Token 和 webhook。当你不拥有 GitHub organization，或者无法安装 App 时，适合使用这种方式。

对于同一个 Repository 资源，这两种模式互斥。

#前提条件

• 已部署并公开暴露 PAC component；请参见 管理 PAC Component。
• PAC webhook URL；请参见 获取 PAC Webhook URL。
• 对 GitHub 仓库的管理员访问权限（用于添加 webhook），或对 GitHub organization 的管理员访问权限（用于安装 App）。
• 一个目标 Kubernetes namespace，用于存放 Repository 资源及其 PipelineRun。
• 对该 namespace 的 kubectl 访问权限。
• 如果使用 tkn pac bootstrap，则需要安装了 pac 插件的 tkn CLI；请参见 tkn pac 命令参考。

#选择一种集成模式

当你管理 GitHub organization，并且计划接入很多仓库时，请使用 GitHub App 模式。当你只需要接入单个仓库、仓库不属于你的 organization，或者无法安装 App 时，请使用 Webhook 模式。

#集成模式 1：GitHub App

#工作原理

GitHub App 在 GitHub organization 或 user 上只安装一次，并将安装范围内每个仓库的事件发送到 PAC controller。PAC 代表该 App 向 GitHub 进行认证。Kubernetes 侧的凭据（App ID、private key、webhook secret）存放在 PAC namespace 中的一个集群级 Secret 里；你无需在 user namespace 中为每个仓库放置任何凭据。

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

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

#选项 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 以及仓库。

#步骤 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 仓库后，普通用户可以在自己的 namespace 中创建一个最小化的 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 manifest，并推送它。PAC 会捕获该事件并在 namespace 中创建一个 PipelineRun。有关文件布局和 annotation 语法，请参见 在 Git 中定义 PipelineRun；有关 PAC 响应的 Git 操作，请参见 触发 Pipeline。

#集成模式 2：Webhook

#工作原理

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

#步骤 1：创建 Personal Access Token

按照 为 PAC 创建 Git Secret 中 GitHub 所需的 scope 进行操作。简而言之，带有 repo scope 的经典 Personal Access Token（如果仅用于 public repository，则使用 public_repo）即可。

#步骤 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:
    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 和 触发 Pipeline。

#验证

当 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。
• 触发 Pipeline — 通过 push、pull request 和 comment 驱动的触发。
• 高级仓库配置 — 并发、参数、自定义设置。
• 配置自定义证书 — 适用于使用 private CA 的 GitHub Enterprise。