配置 GitLab 仓库
本指南将 GitLab 仓库连接到 PAC:准备凭证、创建 Repository 资源、让控制器注册 Webhook,并触发 PipelineRun。
GitLab 使用 Webhook 模式。此模式需要 GitLab 访问令牌和项目 Webhook。启用自动 Webhook 注册后,Webhook 注册控制器会为你创建或更新项目 Webhook。
本页面使用清单和 GitLab Web UI。有关 CLI 工作流,请参阅 tkn pac 命令参考。
目录
前提条件步骤 1:创建 GitLab 访问令牌步骤 2:创建 Kubernetes Secret步骤 3:创建Repository 资源步骤 4:验证自动 Webhook 注册手动回退步骤 5:添加 PipelineRun 并触发它验证排查后续步骤前提条件
- 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 均可使用。
- 在 GitLab 中,打开项目或你的用户 Settings → Access Tokens。
- 创建令牌,并设置:
- Name:描述性名称,例如
pac-integration。 - Scopes:
api。
- Name:描述性名称,例如
- 复制令牌。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:
对于自托管 GitLab,将 spec.url 设置为项目 URL,并将 git_provider.url 设置为 GitLab 实例基础 URL:
对于自托管 GitLab,git_provider.url 必须是 GitLab 实例基础 URL,而不是项目 URL。如果没有 git_provider.url,PAC 可以使用 Repository 的令牌向 https://gitlab.com 报告运行的最终状态。
将 Repository 清单保存为 repository.yaml,然后应用它:
验证:
示例输出:
步骤 4:验证自动 Webhook 注册
创建 Repository 后,Webhook 注册控制器会监视它,并注册 GitLab 项目 Webhook。检查 Repository 注解和事件:
预期状态为 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。
控制器会优先使用来自 spec.git_provider.secret 的令牌。请将该 Repository 本地令牌的 scope 限制为 PAC 的正常访问范围。如果该令牌缺失或没有 Webhook 管理权限,控制器可以使用 Webhook 注册控制器 namespace 中一个匹配的带标签凭证 Secret。集中式 GitLab 凭证需要 api scope,并且令牌身份必须是实例管理员,或对目标项目具有 Maintainer/Owner 访问权限。请参阅为 PAC 创建 Git Secret。
要将某个 Repository 排除在自动 Webhook 注册之外,请将以下标签添加到 Repository 元数据中:
如果控制器已为该 Repository 注册 Webhook,添加该标签会从 GitLab 项目中删除该 Webhook。控制器处理完该标签后,pac.tekton.alauda.io/webhook-registration-status 注解的值为 Skipped,并且 pac.tekton.alauda.io/webhook-registration-reason 的值为 RepositoryOptOut。如果项目仍需要向 PAC 发送事件,请按照手动回退中的说明手动重新注册。
手动回退
如果自动注册已禁用或无法使用,请手动注册 Webhook:
- 打开 GitLab 项目,然后转到 Settings → Webhooks。
- 点击 Add new webhook。
- 填写表单:
- URL:先决条件中提供的 PAC Webhook URL。
- Secret token:存储在 Kubernetes Secret 中的相同
webhook.secret值。 - SSL verification:启用(推荐;仅对于使用自签名证书的非生产环境设置,才取消选中)。
- 在 Trigger 下,选中:
- Push events(选中 All branches,除非你想进行限制)
- Tag push events
- Comments
- Merge request events
- 点击 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。确认:
PAC 控制器日志会显示事件正在处理。读取这些日志需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常只有集群管理员拥有此权限。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会打印最后 10 行,因此以下命令会读取最近 10 分钟内的所有行;如果事件发生时间更早,请增大 --since:
如果没有出现 PipelineRun,请检查控制器日志中是否存在 Webhook Secret 不匹配。PAC 不会拒绝 Secret 令牌错误的请求;它会返回 202,记录错误,并且不会创建 PipelineRun。仅当 Kubernetes Secret 中存储的 webhook.secret 值包含换行符或空格时,PAC 才会在 Repository 上为此错误记录事件:事件为 RepositorySecretValidation,并提示存在该字符。对于其他错误令牌,错误不会作为事件记录在 Repository 上,因此只有能够读取 PAC 命名空间中 Pod 日志的人员才能看到该错误:
示例输出(仅显示消息):
GitLab 会在相关 Pipeline / 合并请求页面上显示 PAC 设置的提交状态。
排查
完整的排查矩阵请参阅常见问题。
后续步骤
- 在 Git 中定义 PipelineRun — 在
.tekton/下定义和演进流水线。 - 触发 PAC Pipelines — 自动事件和评论命令。
- 高级 Repository 配置 — 并发、参数、自定义设置。
- 配置自定义证书 — 适用于使用私有 CA 的自托管 GitLab。
- 通过 TektonConfig 配置增强功能 — 配置自动 Webhook 注册。