Alauda DevOps Pipelines Docs
  • 简体中文

    • 为 PAC 创建 Git Secret

    当你通过 Webhook（不是 GitHub App）将仓库与 PAC 集成时，Repository 资源会引用一个 Kubernetes Secret，其中包含两部分凭据：

    • PAC 用于调用 Git 提供方 API 的 Git 访问令牌（用于读取仓库元数据、发送 commit/status checks、管理 webhook）。
    • Git 提供方在投递事件时附带的 webhook secret，PAC 可据此验证请求是否来自预期来源。

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

    目录

    PAC 如何读取 Secret前提条件步骤 1：创建 Git 访问令牌步骤 2：选择一个 Webhook Secret步骤 3：创建 Kubernetes Secret步骤 4：在 Repository 中引用该 Secret验证更新凭据下一步

    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 中。

    前提条件

    • 一个具有权限在仓库上创建 Personal Access Token (PAT) 的 Git 提供方账户。
    • Repository 资源的目标 namespace。
    • 对该 namespace 的 kubectl 访问权限。

    步骤 1：创建 Git 访问令牌

    在你的 Git 提供方上创建一个 PAT：

    ProviderToken typeRequired scopes
    GitHubPersonal Access Token (classic)公共仓库使用 public_repo，私有仓库使用 repo。如果你打算使用 tkn pac 注册 webhook，请额外添加 admin:repo_hook。
    GitLabPersonal Access Token (or Project Access Token)api

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

    步骤 2：选择一个 Webhook Secret

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

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

    如果你想通过命令行生成一个，可以使用 openssl：

    openssl rand -hex 16

    示例输出：

    a4b1c2d3e4f5061718293a4b5c6d7e8f

    webhook secret 是可选的，但强烈建议配置。如果不配置，任何知道 webhook URL 的人都可以伪造事件。

    步骤 3：创建 Kubernetes Secret

    创建一个 Secret，在默认键下同时存储这两个值。请替换：

    • <git-access-token> 为步骤 1 中的 Git 提供方令牌。

    • <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"）通常表示 token 错误或权限范围不足；完整的排查清单请参见 Common Issues。

    更新凭据

    通过原地更新 Secret 来轮换 token：

    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。

    下一步