为 PAC 创建 Git Secret

当你通过 Webhook(而不是 GitHub App)将 repository 与 PAC 集成时,Repository 资源会引用一个 Kubernetes Secret,其中包含两类凭证:

  • Git 访问令牌:PAC 用它调用 Git provider 的 API(读取 repository 元数据、提交状态检查、管理 webhook)。
  • webhook secret:Git provider 在发送事件时会附带该值,PAC 可以据此验证请求是否来自预期来源。

本指南将为 GitHub Webhook 模式和 GitLab Webhook 模式创建该 Secret。GitHub App 模式不需要按 repository 配置 Secret,因为 controller 使用的是集群范围的 App 凭证。

PAC 如何读取 Secret

PAC 通过 Repository.spec.git_provider 字段查找该 Secret:

spec:
  git_provider:
    secret:
      name: <secret-name>
      key: provider.token       # default: provider.token
    webhook_secret:
      name: <secret-name>
      key: webhook.secret       # default: webhook.secret
  • 如果在 secret 上省略 key,PAC 会读取 provider.token。
  • 如果在 webhook_secret 上省略 key,PAC 会读取 webhook.secret。
  • secret.name 和 webhook_secret.name 可以指向同一个 Secret,也可以指向两个不同的 Secret。

该 Secret 必须与 Repository 资源位于同一个 namespace 中。

前提条件

  • 一个 Git provider 账户,并且有权限在该 repository 上创建 Personal Access Token (PAT)。
  • Repository 资源的目标 namespace。
  • 对该 namespace 的 kubectl 访问权限。

第 1 步:创建 Git 访问令牌

在你的 Git provider 上创建一个 PAT:

提供方令牌类型所需 scope
GitHubPersonal Access Token (classic)公共 repositories 使用 public_repo,私有 repositories 使用 repo。如果你打算使用 tkn pac 注册 webhook,请添加 admin:repo_hook。
GitLabPersonal Access Token (或 Project Access Token)api

请立即复制该令牌。大多数 provider 只会显示一次。

第 2 步:选择一个 Webhook Secret

webhook secret 是 PAC 与 Git provider 之间共享的字符串。PAC 会使用此值验证传入事件。

你可以使用任何足够随机的字符串,例如密码管理器生成的密码。相同的值必须同时存储在 Kubernetes Secret 中,并配置到 Git provider 的 webhook 中。

如果你想从命令行生成一个,openssl 是一种选择:

openssl rand -hex 16

示例输出:

a4b1c2d3e4f5061718293a4b5c6d7e8f

Webhook secret 是可选项,但强烈建议配置。没有它,任何知道 webhook URL 的人都可以伪造事件。

第 3 步:创建 Kubernetes Secret

创建一个 Secret,在默认键下同时存储这两个值。将以下内容替换为:

  • <git-access-token>:第 1 步中的 Git provider 令牌。

  • <webhook-secret>:第 2 步中的共享 webhook secret 字符串。

    kubectl create secret generic <secret-name> \
      --from-literal=provider.token='<git-access-token>' \
      --from-literal=webhook.secret='<webhook-secret>' \
      -n <your-namespace>

示例输出:

secret/my-repo-auth created

或者,也可以通过 manifest 创建:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-auth
  namespace: project-pipelines
type: Opaque
stringData:
  provider.token: glpat-xxxxxxxxxxxxxxxxxxxx
  webhook.secret: a4b1c2d3e4f5061718293a4b5c6d7e8f
kubectl apply -f secret.yaml

第 4 步:在 Repository 中引用该 Secret

在 Repository 资源中,将 git_provider.secret 和 git_provider.webhook_secret 都指向你刚刚创建的 Secret。由于使用的是默认键,因此可以省略 key 字段:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.example.com/team/my-repo
  git_provider:
    type: gitlab
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

如果你将凭证存储在非默认键下,请在这两个字段上显式设置 key。

验证

确认该 Secret 已存在并包含这两个键:

kubectl get secret my-repo-auth -n <your-namespace> \
  -o jsonpath='{.data}' | jq 'keys'

示例输出:

["provider.token", "webhook.secret"]

在创建 Repository 资源后,PAC 日志会显示一次成功查找。请在 PAC namespace 中跟踪 controller 日志:

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

如果 controller 日志中出现认证失败(“401 Unauthorized”、“invalid token”),说明令牌错误或 scope 不足;完整的故障排查清单请参见 Common Issues。

更新凭证

通过原地更新 Secret 来轮换令牌:

kubectl create secret generic my-repo-auth \
  --from-literal=provider.token='<new-token>' \
  --from-literal=webhook.secret='<existing-webhook-secret>' \
  -n <your-namespace> \
  --dry-run=client -o yaml | kubectl apply -f -

PAC 会在每个传入事件时读取该 Secret,因此无需重启 controller。

后续步骤