为 PAC 创建 Git Secret

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

  • PAC 在正常流水线处理期间用于调用 Git provider API 的 Git 访问令牌,例如读取仓库元数据以及发布评论或提交状态。
  • Git provider 在传送事件时包含的 Webhook Secret,PAC 可据此验证请求是否来自预期来源。

本指南将为 GitHub Webhook 模式和 GitLab Webhook 模式创建此 Secret。GitHub App 模式不需要每个仓库单独的 Secret,因为控制器使用集群范围的 App 凭证。

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 必须与 Repository 资源位于同一命名空间中。例外情况是 Repository 同时从全局 Repository CR 继承 secret 和 webhook_secret:此时 PAC 会从全局 Repository 所在的命名空间(PAC 命名空间)读取令牌和 Webhook Secret。请以相同方式设置 secret 和 webhook_secret:两者都位于 Repository 中,并引用其自身命名空间中的 Secret;或者两者都从全局 Repository CR 继承。请参阅创建全局 Repository CR中的行为。

前提条件

  • 具有在该仓库上创建 Personal Access Token(PAT)权限的 Git provider 帐户。
  • 用于 Repository 资源的目标命名空间。
  • 对该命名空间的 kubectl 访问权限。
  • jq CLI,用于验证。

步骤 1:创建 Git 访问令牌

在 Git provider 上创建 PAT。此令牌存储在 Repository 命名空间中,PAC 在正常的流水线处理期间使用它。请将 Webhook 管理权限保留在集中式凭证中,除非你确实希望每个 Repository 所有者都存储一个能够创建或编辑 provider Webhook 的令牌。

Provider令牌类型Repository 本地令牌权限
GitHubPersonal Access Token(classic)公共仓库使用 public_repo,私有仓库使用 repo。对于细粒度 PAT,请授予 Pipelines as Code 文档为 GitHub Webhook 列出的仓库权限:Administration、Metadata 和 Content 为只读,Commit statuses 和 Pull request 为读写权限。除非此本地令牌将直接管理 Webhook,否则不要为其授予 Webhooks 写入权限。
GitLabPersonal Access Token(或 Project Access Token)api。PAC 使用此令牌执行读取项目数据、创建合并请求备注和更新提交状态等操作。配置了集中式凭证后,Repository 本地令牌无需仅为 Webhook 注册而具有 Maintainer/Owner 访问权限。

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

默认启用自动 Webhook 注册(tektoncd-enhancement-config ConfigMap 中的 pac-webhook-registration.enabled: true;请参阅通过 TektonConfig 配置增强功能)。启用此功能后,请创建一个具有 Webhook 管理权限的独立集中式凭证。创建该凭证需要对 Webhook 注册控制器命名空间中的 Secret 具有写入权限(默认安装中的 tekton-pipelines),通常需要集群管理员权限。请参阅集中式 Webhook 注册令牌。

步骤 2:选择 Webhook Secret

Webhook Secret 是 PAC 与 Git provider 之间共享的字符串。PAC 会根据此值验证传入的事件。

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

如果你希望从命令行生成,可以使用 openssl:

openssl rand -hex 16

示例输出:

<32 hexadecimal characters, different on each run>

Webhook Secret 是必需的。PAC 会在启动该事件的 PipelineRun 之前,检查 Git provider Webhook 发送的每个事件是否与此值匹配;传入 Webhook 端点的请求不使用此 Secret,而是根据其自己的 incoming Secret 进行检查(请参阅传入 Webhook)。GitLab Webhook 必须将相同的值作为其 Secret token 发送。在 GitLab 上,即使检查失败,PAC 仍会返回 HTTP 202,但会丢弃该事件且不会创建 PipelineRun;它记录的消息取决于 Webhook 是否发送了 Secret token。不带 Secret token 的 Webhook 会产生 could not validate payload, check your webhook secret?: no X-Gitlab-Token header detected: webhook validation requires a token for security;当自动注册为未引用 Webhook Secret 的 Repository 创建 Webhook 时,也会产生此消息,因为此时控制器注册 Webhook 时不会设置 Secret token。向未引用 Webhook Secret 的 Repository 发送 Secret token 的 Webhook 会产生 could not validate payload, check your webhook secret?: no webhook secret configured: set webhook secret in repository CR or secret。在 GitHub Webhook 模式下,PAC 也会返回 HTTP 202,丢弃此类事件且不会创建 PipelineRun。当 GitHub Webhook 没有 Secret 时,控制器随后会记录一行以 an error occurred: client setup failed: 开头、以 could not validate payload, check your webhook secret?: no signature has been detected, for security reason we are not allowing webhooks that has no secret 结尾的日志;当自动注册为未引用 Webhook Secret 的 Repository 创建 Webhook 时,也是这种情况;如果 Webhook 有 Secret 但 Repository 未引用 Secret,则会记录以 could not validate payload, check your webhook secret?: no webhook secret has been set, in repository CR or secret 开头的日志。

步骤 3:创建 Kubernetes Secret

创建一个 Secret,使用默认键存储这两个值。在 bash 或 zsh 中运行这些命令:在 POSIX sh(例如 dash)中,read -rs 会失败并使变量为空。read -rs 会将值读入 shell 变量而不显示该值,因此令牌和 Webhook Secret 不会出现在屏幕上或 shell 历史记录中。请分别单独运行每个 read -rs 行,然后粘贴值并按 Enter:如果将该行与后续行一起粘贴,不支持括号粘贴的 shell 会将下一行读取为该值。首先从步骤 1 读取 Git provider 令牌:

read -rs GIT_TOKEN

然后从步骤 2 读取共享的 Webhook Secret 字符串:

read -rs WEBHOOK_SECRET

然后创建 Secret。unset 会在创建 Secret 后删除这些变量:

kubectl create secret generic <secret-name> \
  --from-literal=provider.token="$GIT_TOKEN" \
  --from-literal=webhook.secret="$WEBHOOK_SECRET" \
  -n <your-namespace>
unset GIT_TOKEN WEBHOOK_SECRET

示例输出:

secret/<secret-name> created

或者,也可以从 manifest 创建:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-auth
  namespace: project-pipelines
type: Opaque
stringData:
  provider.token: <git-provider-token>
  webhook.secret: <webhook-secret>

将 manifest 保存为 secret.yaml 并应用:

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
    url: https://gitlab.example.com
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

对于自托管 GitLab,还要将 git_provider.url 设置为 GitLab 基础 URL,如示例所示;如果不设置此项,PAC 可以使用此令牌向 https://gitlab.com 报告运行的最终状态。对于 GitLab.com,将其设置为 https://gitlab.com。

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

集中式 Webhook 注册令牌

要自动注册 Webhook,请将具有高权限的 Webhook 管理令牌保存在 Webhook 注册控制器命名空间中带有标签的 Secret 中。当 Repository 所有者不应存储能够创建或编辑 provider Webhook 的令牌时,这种方式非常有用。

集中式 Secret 仅由 Webhook 注册控制器用于注册或更新 Git provider Webhook。PAC 仍从 Repository.spec.git_provider.webhook_secret 读取 Webhook Secret,因此每个 Repository 都必须保留此引用;该引用在 Repository 中设置,或与全局 Repository CR 中的 secret 一起继承(请参阅How PAC reads the Secret)。

集中式令牌需要以下权限:

Provider所需的 Webhook 管理权限
GitHubClassic PAT:admin:repo_hook。Fine-grained PAT:目标 Repository 的 Webhooks 写入权限。
GitLabapi 作用域,并且令牌身份必须是实例管理员,或对目标项目具有 Maintainer/Owner 访问权限。

对于每种 provider 类型和 provider URL,在 Webhook 注册控制器命名空间中准确创建一个匹配的集中式 Secret。该命名空间是 tektoncd-enhancement-controller Deployment 所在的命名空间;在默认安装中为 tekton-pipelines;请将 <controller-namespace> 替换为该命名空间。在此处创建 Secret 需要对该命名空间中的 Secrets 具有写入权限,通常需要集群管理员权限:

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 注册控制器运行所在的命名空间中。在默认安装中,该命名空间为 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 包含可用令牌,则会首先尝试使用该令牌。如果该令牌缺少 Webhook 管理权限,控制器会使用匹配的集中式 Secret 重试。

验证

确认 Secret 存在,并且两个键都包含值:

kubectl get secret <secret-name> -n <your-namespace> \
  -o json | jq '.data | map_values(length)'

对于 26 个字符的令牌以及 Step 2 的 openssl 命令打印的 32 个字符的 Webhook Secret,示例输出如下:

{
  "provider.token": 36,
  "webhook.secret": 44
}

这些数字是经过 base64 编码的值的长度。例如,具有 0 的键为空,可能是因为 Step 3 中的 read -rs 失败;请使用更新凭证中的命令再次设置两个值,这些命令会原地更新现有 Secret。对于已存在的 Secret,再次运行 Step 3 中的 kubectl create secret generic 命令会因 error: failed to create secret secrets "<secret-name>" already exists 而失败。长度超过 0 并不能说明值正确;下面的事件检查可以验证这一点。

启用自动 Webhook 注册后,请在创建 Repository 后立即检查它,如配置 GitLab Repository或配置 GitHub Repository的 Step 4 中所示。如果 git_provider.webhook_secret 引用的 Secret 不存在,或者它引用的键为空,Webhook 注册控制器会将 pac.tekton.alauda.io/webhook-registration-status 注解设置为 Failed,并将 pac.tekton.alauda.io/webhook-registration-reason 设置为 MissingWebhookSecret。

PAC 仅在处理 Repository 的事件时读取 Secret,因此创建 Repository 资源不会记录与其相关的任何日志。要检查 Secret,请发送一个事件(例如推送提交),并确认已创建 PipelineRun;在 GitLab 上,还要确认其状态显示在提交或合并请求中(请参阅配置 GitLab Repository)。此检查需要项目上存在 Webhook,该 Webhook 可以自动注册或手动注册;还需要在 .tekton/ 下存在其注解与事件匹配的 PipelineRun。没有这些条件,即使 Secret 正确,也不会创建 PipelineRun。如果没有出现 PipelineRun,请读取 PAC 命名空间中的控制器日志。这需要对其中 Pod 日志的读取权限,通常只有集群管理员具备该权限;下面的 Secret 缺失错误不会作为 Repository 上的事件记录。使用 -l 时,kubectl logs 仅打印最后 10 行,除非设置了 --tail,因此该命令会读取最近 10 分钟内的每一行;如果事件更早,请增大 --since:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1

如果 Repository 引用或继承的 Secret 不存在于 PAC 读取它的命名空间中(请参阅 PAC 如何读取 Secret),日志会针对该事件显示 cannot get secret from repository: secrets "<name>" not found,并且不会创建 PipelineRun。

在 GitLab 上,令牌问题会以以下两种方式之一表现出来:

  • 如果 GitLab 拒绝令牌(例如令牌错误),PAC 不会创建 PipelineRun。控制器日志行取决于事件。对于推送事件,PAC 无法读取 .tekton/,日志会显示 failed to list .tekton dir: GET https://<gitlab-host>/api/v4/projects/<id>/repository/tree: 401 {message: 401 Unauthorized}。对于合并请求事件或合并请求评论,PAC 会先检查对源项目的访问权限,日志会显示 failed to access GitLab source repository ID <id>: please ensure token has 'read_repository' scope on that repository,随后显示 GitLab 返回的错误。

  • 如果令牌可以读取 Repository,但缺少 api 作用域(例如 read_api 令牌),PAC 会创建并运行 PipelineRun,但提交或合并请求上不会显示状态。Repository 会记录带有 403 {error: insufficient_scope} 的 FailedToSetCommitStatus 事件;无需访问 PAC 命名空间即可查看该事件。事件只会保留有限时间,因此请在事件发生后尽快检查:

    kubectl get events -n <your-namespace> --field-selector involvedObject.kind=Repository

如果自托管 GitLab 的 FailedToSetCommitStatus 事件显示 POST https://gitlab.com/api/v4/projects/<id>/statuses/<sha>,则 Repository 没有 git_provider.url;请按照Step 4中的说明进行设置。

请参阅常见问题获取完整的故障排查清单。

更新凭证

通过原位更新 Secret 轮换令牌。下面的命令适用于一个 Secret,该 Secret 按照Step 3中的说明,在默认键 provider.token 和 webhook.secret 下保存两个值;如果 Repository 设置了其他 key 名称,或引用了两个 Secret(请参阅 PAC 如何读取 Secret),请在命令中使用相应的键名和 Secret 名称。与 Step 3 一样,请在 bash 或 zsh 中运行命令,并单独运行每一行 read -rs 命令,然后粘贴值并按 Enter。首先读取新令牌:

read -rs GIT_TOKEN

然后将 Secret 的 webhook.secret 键中的当前 Webhook Secret 复制到变量中,以便更新时保留该值。该命令不会显示该值;它需要读取 Secret 的权限:

WEBHOOK_SECRET=$(kubectl get secret <secret-name> -n <your-namespace> -o jsonpath='{.data.webhook\.secret}' | base64 -d)

如果该键为空(Verification中的 0),请改为读取Step 2中的 Webhook Secret:

read -rs WEBHOOK_SECRET

然后更新 Repository 引用的 Secret,并删除这些变量:

kubectl create secret generic <secret-name> \
  --from-literal=provider.token="$GIT_TOKEN" \
  --from-literal=webhook.secret="$WEBHOOK_SECRET" \
  -n <your-namespace> \
  --dry-run=client -o yaml | kubectl apply -f -
unset GIT_TOKEN WEBHOOK_SECRET

对于使用Step 3中的 kubectl create secret generic 命令创建的 Secret,第一个 kubectl apply 会警告 Secret 缺少 kubectl.kubernetes.io/last-applied-configuration 注解;Secret 仍会完成更新,最后一行输出为 secret/<secret-name> configured。

然后运行Verification中的检查。

PAC 会在每个传入事件发生时读取 Secret,因此无需重启控制器。自动 Webhook 注册也会对直接引用的 Repository Secret 的更改作出响应,而无需在这些 Secret 上设置标签。

更新集中式 Webhook 注册凭证时,Webhook 注册控制器会刷新与旧的或新的提供商标签和 URL 匹配的 Repository。删除集中式凭证标签或更改提供商 URL 后,依赖旧凭证的现有 Repository 会再次进行协调,并报告当前凭证状态。

平台约定

启用时机。当许多 Repository 以 Webhook 模式接入 PAC,且每个 Repository 否则都需要使用自己的高权限令牌来创建提供商 Webhook 时,请应用这些约定。项目只需在自己的命名空间中创建一个 Secret,并在其 Repository 中引用该 Secret。GitHub App 模式不使用每个 Repository 的 Secret 或自动 Webhook 注册,因此这些约定不适用于该模式。

推荐值。每个 Repository 都引用其自身命名空间中的一个 Secret,该 Secret 保存 provider.token 和 webhook.secret:按照 Step 3 中的说明创建该 Secret,并在 spec.git_provider.secret 和 spec.git_provider.webhook_secret 中同时引用它;其令牌仅具有 Step 1 中列出的 Repository 本地权限。Webhook 管理令牌集中存储:在 Webhook 注册控制器命名空间中(默认安装中为 tekton-pipelines),每种提供商类型和提供商 URL 各设置一个带标签的 Secret,如集中式 Webhook 注册令牌中所述。控制器会先尝试使用 Repository 令牌;由于该令牌没有 Webhook 管理权限,控制器会回退到集中式令牌,为每个 Repository 注册 Webhook。可选地,PAC 命名空间中的全局 Repository CR 可以保存共享的 git_provider 设置,使 Repository 只需声明其 url 和 git_provider.type。当 Repository 通过这种方式继承 secret 和 webhook_secret 时,PAC 会从 PAC 命名空间(默认安装中为 tekton-pipelines)读取其令牌和 Webhook Secret,而不是从 Repository 的命名空间读取(请参阅How PAC reads the Secret),因此每个继承 secret 的 Repository 都使用相同的令牌。保留 Repository 本地令牌的 Repository 必须设置自己的 git_provider.secret 和 git_provider.webhook_secret。此功能处于 Technology Preview 阶段,请参阅创建全局 Repository CR。要确认注册正常工作,请检查每个项目 Repository 的 pac.tekton.alauda.io/webhook-registration-status 注解是否为 Registered(控制器不会注册全局 Repository CR),具体说明请参阅配置 GitLab Repository和配置 GitHub Repository中的步骤 4。要停止使用集中式令牌,请先为每个保留自动注册的 Repository 的令牌授予集中式 Webhook 注册令牌中列出的 Webhook 管理权限,然后从集中式 Secret 中移除 pac.tekton.alauda.io/provider-credential 标签或删除该 Secret。如果某个 Repository 自身的令牌缺少该权限,则会显示 Failed,原因是 ProviderAPIError,并且控制器会保留其现有 Webhook。要停止使用全局 Repository CR,请参阅停止使用全局 Repository CR。

先决条件。必须通过 tektoncd-enhancement-controller 启用自动 Webhook 注册;有关 pac-webhook-registration.* 设置,请参阅通过 TektonConfig 配置增强功能。平台团队需要具有在 Webhook 注册控制器命名空间中创建 Secret 的权限,以及持有集中式 Webhook 注册令牌中所列 Webhook 管理权限的提供商身份。如果提供商 API 使用私有 CA,则必须先完成配置自定义证书中的控制器信任配置。

后续步骤