配置 GitLab Repository

本指南介绍如何将 GitLab repository 连接到 PAC:准备凭据、创建 Repository 资源、注册 webhook,并触发 PipelineRun。

GitLab 使用 Webhook 模式。每个 repository 都会配置一个 GitLab access token 和一个 project webhook。

本页使用 manifests 和 GitLab Web UI。关于 CLI 工作流,请参见 tkn pac 命令参考。

前提条件

  • PAC component 已部署并对 GitLab 暴露;参见 管理 PAC Component。
  • PAC webhook URL;参见 获取 PAC Webhook URL。
  • 对 GitLab project 的 Maintainer 访问权限(添加 webhook 所必需)。
  • 一个目标 Kubernetes namespace,Repository 资源及其 PipelineRun 将在其中运行。
  • 对该 namespace 的 kubectl 访问权限。

第 1 步:创建 GitLab Access Token

PAC 需要一个 token 来读取 project metadata、发布 merge request comments,并更新 commit status。Personal Access Token 和 Project Access Token 均可使用。

  1. 在 GitLab 中,打开 project 或你的用户 Settings → Access Tokens。
  2. 创建一个具有以下配置的 token:
    • Name:描述性名称,例如 pac-integration。
    • Scopes:api。
  3. 复制 token。GitLab 只会显示一次。

第 2 步:创建 Kubernetes Secret

创建一个同时包含 GitLab token 和 webhook secret 的 Secret。请参照 为 PAC 创建 Git Secret。

在本指南的后续部分中,该 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
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config

对于自托管 GitLab,将 spec.url 设置为 project URL,并添加 git_provider.url,其值为 GitLab instance 的 base 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 instance 的 base URL,而不是 project URL。

应用它:

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 步:在 GitLab 中注册 webhook

  1. 打开 GitLab project,然后进入 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 操作。返回 200 响应表示 controller 已接收并接受该事件。

第 5 步:添加 PipelineRun 并触发它

在 repository 的 .tekton/ 下添加一个 PipelineRun manifest 并将其推送。PAC 会从事件触发所在的 branch 读取该文件,将 annotations 与事件进行匹配,并在该 namespace 中创建一个 PipelineRun。

有关文件布局和 annotation 语法,请参见 在 Git 中定义 PipelineRuns;有关 PAC 响应的 Git 操作,请参见 触发 Pipelines。

验证

当 Git event 到达后,PAC 会在 Repository 的 namespace 中创建一个 PipelineRun。确认:

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

PAC controller 日志会显示该事件正在处理中:

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

GitLab 会在相关 pipeline / merge request 页面显示 PAC 设置的 commit status。

故障排查

症状首先检查
Webhook test 返回 Hook executed successfully,但没有出现 PipelineRun.tekton/ 下存在一个 PipelineRun manifest,并且其 annotations 与该事件匹配。参见 在 Git 中定义 PipelineRuns。
Webhook test 失败并提示 connection refusedPAC webhook URL 可从 GitLab 访问。参见 获取 PAC Webhook URL。
Webhook test 失败并返回 401 或 403GitLab 中配置的 webhook.secret 与 Kubernetes Secret 中的值一致。
repositories status 显示为 failed运行 kubectl describe repository <name> -n <ns>;常见原因包括无法访问的 git_provider.url 或已过期的 token。
未收到自托管 GitLab 事件git_provider.url 设置为 GitLab base URL,而不是 project URL。
未将 status checks 回传到 GitLab该 token 具有 api scope 且未过期。

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

后续步骤