#配置 GitHub Repository

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

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

• GitHub App — 由管理员在 GitHub organization（或 user）上一次性安装一个 GitHub App。随后，属于该安装的每个 repository 都通过仅包含 URL 的 Repository 资源来表示；无需为每个 repository 配置令牌或 webhook。
• Webhook — 按 repository 配置 Personal Access Token 和 webhook。当你不拥有 GitHub organization 或无法安装 App 时适用。

对于给定的 Repository 资源，这两种模式互斥。

#前提条件

• 已部署并暴露 PAC 组件；参见 Manage PAC Component。
• PAC webhook URL；参见 Get the PAC Webhook URL。
• 具有 GitHub repository 的管理员访问权限（用于添加 webhook）或 GitHub organization 的管理员访问权限（用于安装 App）。
• 一个目标 Kubernetes namespace，用于存放 Repository 资源及其 PipelineRun。
• 该 namespace 的 kubectl 访问权限。
• 已安装 pac 插件的 tkn CLI，如果你使用 tkn pac bootstrap；参见 tkn pac Command Reference。

#选择集成模式

当你管理 GitHub organization 并计划接入多个 repository 时，请使用 GitHub App 模式。当只处理一个一次性 repository、organization 之外的 repository，或者无法安装 App 时，请使用 Webhook 模式。

#集成模式 1：GitHub App

#工作原理

一个 GitHub App 只需在 GitHub organization 或 user 上安装一次，便会将该安装中每个 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 的创建，并将生成的凭据存储到集群 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 以及 repositories。

#步骤 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 资源即可。只需要 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

在 repository 中的 .tekton/ 下添加一个 PipelineRun 清单并推送。PAC 会接收该事件并在 namespace 中创建一个 PipelineRun。有关文件布局和注解语法，请参见 Define PipelineRuns in Git；有关自动触发和基于注释的触发，请参见 Trigger PAC Pipelines。

#集成模式 2：Webhook

#工作原理

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

#步骤 1：创建 Personal Access Token

关于 GitHub 所需的 scopes，请参见 Create a Git Secret for PAC。简而言之，带有 repo scope 的经典 Personal Access Token（如果仅针对公开 repository，则使用 public_repo）即可。

#步骤 2：创建 Kubernetes Secret

创建一个同时包含 Git access token 和 webhook secret 的 Secret。操作步骤请参见 Create a Git Secret for PAC。

在本指南后续部分中，该 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 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。请参见 Define PipelineRuns in Git 和 Trigger 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 模式：链接回集群的 commit status。

#故障排查

完整的故障排查矩阵请参见 Common Issues。

#下一步

• Define PipelineRuns in Git — 在 .tekton/ 下定义并演进 pipeline。
• Trigger PAC Pipelines — 自动事件和注释命令。
• Advanced Repository Configuration — 并发、参数、自定义设置。
• Configure Custom Certificates — 适用于具有私有 CA 的 GitHub Enterprise。