配置 GitLab 仓库

本指南将 GitLab 仓库连接到 PAC:准备凭证、创建 Repository 资源、让控制器注册 Webhook,并触发 PipelineRun。

GitLab 使用 Webhook 模式。此模式需要 GitLab 访问令牌和项目 Webhook。启用自动 Webhook 注册后,Webhook 注册控制器会为你创建或更新项目 Webhook。

本页面使用清单和 GitLab Web UI。有关 CLI 工作流,请参阅 tkn pac 命令参考。

前提条件

  • PAC 组件已部署并向 GitLab 暴露;请参阅管理 PAC 组件。
  • PAC Webhook URL 已记录在 pipelines-as-code-info.data.controller-url 中。有关设置和验证,请参阅获取 PAC Webhook URL。
  • 对 GitLab 项目具有 Maintainer 访问权限,或拥有管理项目 Webhook 的权限的令牌。
  • 用于存放 Repository 资源及其 PipelineRun 的目标 Kubernetes namespace。
  • 对该 namespace 具有 kubectl 访问权限。

步骤 1:创建 GitLab 访问令牌

PAC 需要令牌来读取项目元数据、发布合并请求评论以及更新提交状态。Personal Access Token 或 Project Access Token 均可使用。

  1. 在 GitLab 中,打开项目或你的用户 Settings → Access Tokens。
  2. 创建令牌,并设置:
    • Name:描述性名称,例如 pac-integration。
    • Scopes:api。
  3. 复制令牌。GitLab 只会显示一次。

此仓库本地令牌由 PAC 在正常流水线处理期间使用。当配置了集中式 Webhook 注册凭证时,仅进行 Webhook 注册并不需要 Maintainer/Owner 访问权限。

要启用自动 Webhook 注册,请配置具有 api scope 的匹配集中式凭证。令牌身份必须是实例管理员,或对目标项目具有 Maintainer/Owner 访问权限。该凭证是 Webhook 注册控制器 namespace 中的 Secret(默认安装中为 tekton-pipelines);创建它需要对其中的 Secrets 具有写入权限,通常由集群管理员完成。请参阅集中式 Webhook 注册令牌。

步骤 2:创建 Kubernetes Secret

创建一个包含 GitLab 令牌和 Webhook 密钥的 Secret。按照为 PAC 创建 Git Secret中的步骤 2 和步骤 3 操作,并在 namespace project-pipelines 中将 Secret 创建为 gitlab-webhook-config:在清单中,将 <secret-name> 和 <your-namespace>,或 metadata.name 和 metadata.namespace 设置为这些名称。

在本指南的其余部分中,该 Secret 名称为 gitlab-webhook-config。

步骤 3:创建 Repository 资源

Repository 引用该 Secret。对于 GitLab.com:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.com/<group>/<project>
  git_provider:
    type: gitlab
    url: https://gitlab.com
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config

对于自托管 GitLab,将 spec.url 设置为项目 URL,并将 git_provider.url 设置为 GitLab 实例基础 URL:

spec:
  url: https://gitlab.example.com/<group>/<project>
  git_provider:
    type: gitlab
    url: https://gitlab.example.com
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config
INFO

对于自托管 GitLab,git_provider.url 必须是 GitLab 实例基础 URL,而不是项目 URL。如果没有 git_provider.url,PAC 可以使用 Repository 的令牌向 https://gitlab.com 报告运行的最终状态。

将 Repository 清单保存为 repository.yaml,然后应用它:

kubectl apply -f repository.yaml

验证:

kubectl get repositories -n project-pipelines

示例输出:

NAME      URL                                       SUCCEEDED   REASON   STARTTIME   COMPLETIONTIME
my-repo   https://gitlab.com/group/project

步骤 4:验证自动 Webhook 注册

创建 Repository 后,Webhook 注册控制器会监视它,并注册 GitLab 项目 Webhook。检查 Repository 注解和事件:

kubectl describe repository my-repo -n project-pipelines
kubectl get repository my-repo -n project-pipelines \
  -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-status}'

预期状态为 Registered。控制器会创建或更新包含以下内容的 GitLab Webhook:

  • URL:公开的 PAC Webhook URL
  • Secret 令牌:spec.git_provider.webhook_secret 引用的 webhook.secret 值
  • 事件:推送、标签推送、评论和合并请求
  • SSL 验证:默认启用

自动注册由 tektoncd-enhancement-controller 配置。有关 pac-webhook-registration.* 设置(包括提供商端 TLS 验证),请参阅通过 TektonConfig 配置增强功能。如果 GitLab API 使用私有 CA,还应按照配置自定义证书配置控制器信任设置。

控制器会将 GitLab Hook ID 记录在 pac.tekton.alauda.io/webhook-managed-ref 中。如果 PAC Webhook URL 后续发生变化,控制器会根据记录的 Hook ID 更新该 Hook,而不是为同一项目创建重复的 Hook。

INFO

控制器会优先使用来自 spec.git_provider.secret 的令牌。请将该 Repository 本地令牌的 scope 限制为 PAC 的正常访问范围。如果该令牌缺失或没有 Webhook 管理权限,控制器可以使用 Webhook 注册控制器 namespace 中一个匹配的带标签凭证 Secret。集中式 GitLab 凭证需要 api scope,并且令牌身份必须是实例管理员,或对目标项目具有 Maintainer/Owner 访问权限。请参阅为 PAC 创建 Git Secret。

要将某个 Repository 排除在自动 Webhook 注册之外,请将以下标签添加到 Repository 元数据中:

metadata:
  labels:
    pac.tekton.alauda.io/webhook-registration-disabled: "true"

如果控制器已为该 Repository 注册 Webhook,添加该标签会从 GitLab 项目中删除该 Webhook。控制器处理完该标签后,pac.tekton.alauda.io/webhook-registration-status 注解的值为 Skipped,并且 pac.tekton.alauda.io/webhook-registration-reason 的值为 RepositoryOptOut。如果项目仍需要向 PAC 发送事件,请按照手动回退中的说明手动重新注册。

手动回退

如果自动注册已禁用或无法使用,请手动注册 Webhook:

  1. 打开 GitLab 项目,然后转到 Settings → Webhooks。
  2. 点击 Add new webhook。
  3. 填写表单:
    • URL:先决条件中提供的 PAC Webhook URL。
    • Secret token:存储在 Kubernetes Secret 中的相同 webhook.secret 值。
    • SSL verification:启用(推荐;仅对于使用自签名证书的非生产环境设置,才取消选中)。
  4. 在 Trigger 下,选中:
    • Push events(选中 All branches,除非你想进行限制)
    • Tag push events
    • Comments
    • Merge request events
  5. 点击 Add webhook。

GitLab 在 Webhook 条目下提供 Test → Push events 操作。PAC 会返回 HTTP 202,正文为 {"status":202,"message":"accepted"}。这仅表示控制器已收到请求:PAC 会在响应后检查 Secret 令牌,并匹配 .tekton/ PipelineRuns,因此错误的 Secret 令牌也会获得 202。按照验证中的说明,使用 kubectl get pipelineruns 并检查 PAC 控制器日志来查看结果。

步骤 5:添加 PipelineRun 并触发它

在仓库的 .tekton/ 下添加 PipelineRun 清单并推送。PAC 从事件触发所在的分支读取文件,将注解与事件进行匹配,并在该命名空间中创建一个 PipelineRun。使用 pipelinerun_provenance: default_branch 替代默认值 source 后,无论合并请求来自哪个分支,PAC 都会从名称为仓库默认分支的分支(例如 main)读取文件;请参阅源分支配置。

有关文件布局和注解语法,请参阅在 Git 中定义 PipelineRuns;有关自动触发和基于评论的触发,请参阅触发 PAC Pipeline。

验证

Git 事件到达后,PAC 会在 Repository 的命名空间中创建一个 PipelineRun。确认:

kubectl get pipelineruns -n project-pipelines \
  -l pipelinesascode.tekton.dev/repository=my-repo

PAC 控制器日志会显示事件正在处理。读取这些日志需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常只有集群管理员拥有此权限。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会打印最后 10 行,因此以下命令会读取最近 10 分钟内的所有行;如果事件发生时间更早,请增大 --since:

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

如果没有出现 PipelineRun,请检查控制器日志中是否存在 Webhook Secret 不匹配。PAC 不会拒绝 Secret 令牌错误的请求;它会返回 202,记录错误,并且不会创建 PipelineRun。仅当 Kubernetes Secret 中存储的 webhook.secret 值包含换行符或空格时,PAC 才会在 Repository 上为此错误记录事件:事件为 RepositorySecretValidation,并提示存在该字符。对于其他错误令牌,错误不会作为事件记录在 Repository 上,因此只有能够读取 PAC 命名空间中 Pod 日志的人员才能看到该错误:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1 | grep "check your webhook secret"

示例输出(仅显示消息):

an error occurred: client setup failed: could not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secret

GitLab 会在相关 Pipeline / 合并请求页面上显示 PAC 设置的提交状态。

排查

症状首先检查
Webhook 测试成功(HTTP 202),但没有出现 PipelineRun控制器日志中没有 Webhook Secret 错误(请参阅验证以及下面的 Secret 令牌行)。然后检查:.tekton/ 下是否存在 PipelineRun 清单,并且其注解是否与事件匹配。请参阅在 Git 中定义 PipelineRun。
Webhook 测试失败并显示 connection refusedPAC Webhook URL 可从 GitLab 访问。请参阅获取 PAC Webhook URL。
Webhook 测试成功(HTTP 202),没有出现 PipelineRun,且控制器日志显示 could not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secretGitLab Webhook 的 Secret 令牌与 Kubernetes Secret 中的 webhook.secret 值匹配。PAC 不会使用 401 或 403 拒绝错误令牌:它会接受请求,记录此错误,并且不会创建 PipelineRun。
Webhook 测试成功(HTTP 202),没有出现 PipelineRun,且控制器日志显示 could not validate payload, check your webhook secret?: no webhook secret configured: set webhook secret in repository CR or secretRepository 引用的 Kubernetes Secret,其中的 git_provider.webhook_secret 字段保存了 Webhook Secret。如果没有 Webhook Secret,PAC 会丢弃与 Repository 对应的每个 GitLab Webhook 事件;向传入 Webhook 端点发送的请求不使用 Webhook Secret。请参阅创建 Git Secret。
Webhook 测试成功(HTTP 202),没有出现 PipelineRun,且控制器日志显示 could not validate payload, check your webhook secret?: no X-Gitlab-Token header detected: webhook validation requires a token for securityGitLab Webhook 未发送 Secret 令牌。首先检查 Repository 是否引用了 Kubernetes Secret,其中的 git_provider.webhook_secret 字段保存 Webhook Secret:自动注册时,控制器随后会使用该字段中的值设置 Webhook 的 Secret 令牌。对于手动添加的 Webhook,请将其 Secret 令牌设置为 Kubernetes Secret 中的 webhook.secret 值。
Repository 注解 webhook-registration-status=Failed运行 kubectl describe repository <name> -n <ns> 并检查 pac.tekton.alauda.io/webhook-registration-reason。常见原因包括缺少 Secret、git_provider.webhook_secret 引用的键为空(原因 MissingWebhookSecret)、缺少令牌、令牌权限不足、错误的 git_provider.url(当它是项目 URL 时,原因是 InvalidRepository),或证书不受信任。Hook URL 返回状态 404 或 405 的 ProviderAPIError 表示 GitLab 项目已移动、重命名或计划删除;请将 spec.url 指向当前项目路径。
自托管 GitLab:Webhook 测试成功(HTTP 202),但没有出现 PipelineRun,且控制器日志显示 failed to list .tekton dir: Get \"https://<gitlab-host>/<group>/<project>/api/v4/...;或者 Repository 具有 pac.tekton.alauda.io/webhook-registration-reason=InvalidRepository,其消息为 GitLab repository path is emptygit_provider.url 是 GitLab 实例的基本 URL(例如 https://gitlab.example.com),而不是项目 URL。PAC 会将 /api/v4 附加到 git_provider.url,因此项目 URL 会使其 GitLab API 调用发送到错误路径,并导致自动 Webhook 注册失败。
状态检查未回传到 GitLab令牌具有 api 作用域且尚未过期。Repository 事件会显示错误;事件仅保留有限时间,因此请在事件发生后尽快检查:对于不具有 api 作用域的令牌,kubectl get events -n <ns> --field-selector involvedObject.kind=Repository 会列出带有 403 {error: insufficient_scope} 的 FailedToSetCommitStatus;对于没有 git_provider.url 的 Repository,在自托管 GitLab 中则会列出带有 POST https://gitlab.com/api/v4/projects/<id>/statuses/<sha> 的事件。

完整的排查矩阵请参阅常见问题。

后续步骤