Alauda DevOps Pipelines Docs
  • 简体中文

    • 为 PAC 创建 Git Secret

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

    • Git access token：PAC 在正常 pipeline 处理期间调用 Git provider 的 API 时使用，例如读取仓库元数据以及发布评论或 commit status。
    • webhook secret：Git provider 在投递事件时会附带该 secret，PAC 可据此验证请求是否来自预期来源。

    本指南将为 GitHub Webhook 模式和 GitLab Webhook 模式创建该 Secret。GitHub App 模式不需要按仓库划分的 Secret，因为控制器使用集群级别的 App 凭证。

    目录

    PAC 如何读取 Secret前提条件步骤 1：创建 Git Access Token步骤 2：选择一个 Webhook Secret步骤 3：创建 Kubernetes Secret步骤 4：在 Repository 中引用该 Secret集中式 webhook 注册 token验证更新凭证后续步骤

    PAC 如何读取 Secret

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

    spec:
  git_provider:
    type: gitlab                # or github
    secret:
      name: <secret-name>
      key: provider.token       # default: provider.token
    webhook_secret:
      name: <secret-name>
      key: webhook.secret       # default: webhook.secret
    • 将 type 设置为该 Repository 使用的 Git provider，例如 github 或 gitlab。
    • 如果 secret 上省略了 key，PAC 会读取 provider.token。
    • 如果 webhook_secret 上省略了 key，PAC 会读取 webhook.secret。
    • secret.name 和 webhook_secret.name 可以指向同一个 Secret，也可以指向两个不同的 Secret。

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

    前提条件

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

    步骤 1：创建 Git Access Token

    在你的 Git provider 上创建一个 PAT。该 token 会存储在 Repository namespace 中，并由 PAC 在正常 pipeline 处理期间使用。如果你不希望每个 Repository 所有者都保存一个可创建或编辑 provider webhook 的 token，请将 webhook 管理权限保存在集中式凭证中。

    ProviderToken typeRepository 本地 token 权限
    GitHubPersonal Access Token (classic)公共仓库使用 public_repo，私有仓库使用 repo。对于 fine-grained PAT，仅授予 PAC 在工作流中所需的仓库权限，例如 repository content 读权限、commit status 写权限以及 comment 写权限。除非该 token 将直接管理 webhook，否则不要授予此本地 token Webhooks 写权限。
    GitLabPersonal Access Token (or Project Access Token)api，并具备 PAC 操作所需的常规 project 访问权限，例如读取 project 数据、创建 merge request notes 以及更新 commit statuses。只要已配置集中式凭证，Repository 本地 token 就不需要仅为了 webhook 注册而拥有 Maintainer/Owner 访问权限。

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

    如果启用了自动 webhook 注册，请创建一个单独的、具有 webhook 管理权限的集中式凭证。请参阅 集中式 webhook 注册 token。

    步骤 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 token。

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

    集中式 webhook 注册 token

    对于自动 webhook 注册，请将高权限的 webhook 管理 token 保存在 webhook registration controller namespace 中带标签的 Secret 里。当 Repository 所有者不应保存可创建或编辑 provider webhook 的 token 时，这种方式非常有用。

    集中式 Secret 仅由 webhook registration controller 用于注册或更新 Git provider webhook。PAC 仍然会从 Repository.spec.git_provider.webhook_secret 读取 webhook secret，因此每个 Repository 都必须保留该引用。

    集中式 token 需要以下权限：

    Provider所需的 webhook 管理权限
    GitHubClassic PAT：admin:repo_hook。Fine-grained PAT：目标 repository 的 Webhooks 写权限。
    GitLabapi scope，并且 token 身份必须是实例管理员，或者对目标 project 具有 Maintainer/Owner 访问权限。

    在 webhook registration controller namespace 中，为每种 provider type 和 provider URL 恰好创建一个匹配的集中式 Secret：

    apiVersion: v1
kind: Secret
metadata:
  name: gitlab-webhook-admin
  namespace: <controller-namespace>
  labels:
    pac.tekton.alauda.io/provider-credential: "true"
    pac.tekton.alauda.io/provider-type: gitlab
  annotations:
    pac.tekton.alauda.io/provider-url: https://gitlab.example.com
type: Opaque
stringData:
  provider.token: <token-with-webhook-management-permission>

    对于 GitHub.com，请使用 https://api.github.com 作为 provider URL。对于 GitHub Enterprise，请使用 Enterprise API URL，例如 https://github.example.com/api/v3。

    示例：

    metadata:
  labels:
    pac.tekton.alauda.io/provider-credential: "true"
    pac.tekton.alauda.io/provider-type: github
  annotations:
    pac.tekton.alauda.io/provider-url: https://api.github.com

    匹配规则：

    • Secret 必须位于 webhook registration controller 运行的 namespace 中。在默认安装中，该 namespace 为 tekton-pipelines。
    • Secret 必须包含 pac.tekton.alauda.io/provider-credential: "true"，这样控制器才会将其视为集中式凭证。
    • provider-type 必须与 spec.git_provider.type 匹配。
    • pac.tekton.alauda.io/provider-url 注解在匹配前会被规范化。对于 GitLab，https://gitlab.example.com 和 https://gitlab.example.com/api/v4 都会匹配同一个 provider。对于 GitHub Enterprise，请使用 API URL，例如 https://github.example.com/api/v3。
    • 如果多个 Secret 匹配同一个 provider，注册会因 AmbiguousCredential 而失败。
    • 如果 spec.git_provider.secret 中包含可用 token，会优先尝试该 token。如果该 token 缺少 webhook 管理权限，控制器会使用匹配的集中式 Secret 重试。

    验证

    确认该 Secret 已存在，并且包含这两个键：

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

    示例输出：

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

    在创建 Repository 资源后，PAC 日志中应显示成功查找。请在 PAC namespace 中查看控制器日志：

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

    如果控制器日志中出现认证失败（"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，因此无需重启控制器。自动 webhook 注册也会响应对直接引用的 Repository Secrets 的变更，而无需在这些 Secrets 上添加标签。

    当集中式 webhook 注册凭证更新时，webhook registration controller 会刷新与旧 provider 标签或新 provider 标签及 URL 任一匹配的 Repositories。如果你移除了集中式凭证标签或更改了 provider URL，那么依赖旧凭证的现有 Repositories 会重新进行协调，并报告当前的凭证状态。

    后续步骤