#配置 GitLab 仓库

本指南将 GitLab 仓库连接到 PAC：准备凭证、创建 Repository 资源、让 controller 注册 webhook，并触发 PipelineRun。

GitLab 使用 Webhook 模式。需要 GitLab access token 和项目 webhook。启用自动 webhook 注册后，webhook 注册 controller 会为你创建或更新项目 webhook。

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

#前提条件

• 已部署并对 GitLab 暴露 PAC component；请参见 管理 PAC Component。
• PAC webhook URL 已记录在 pipelines-as-code-info.data.controller-url 中。有关设置和验证，请参见 获取 PAC Webhook URL。
• 具有 GitLab 项目的 Maintainer 权限，或者具有管理项目 webhook 权限的 token。
• 一个目标 Kubernetes namespace，用于存放 Repository 资源及其 PipelineRuns。
• 对该 namespace 的 kubectl 访问权限。

#第 1 步：创建 GitLab Access Token

PAC 需要一个 token 来读取项目元数据、提交 merge request 评论以及更新 commit 状态。Personal Access Token 或 Project Access Token 都可以。

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

此 Repository 本地 token 由 PAC 在正常 pipeline 处理期间使用。若已配置集中式 webhook 注册凭证，仅为 webhook 注册本身并不需要 Maintainer/Owner 访问权限。

对于自动 webhook 注册，请配置一个匹配的、具有 api scope 的集中式凭证。token 身份必须是 instance administrator，或者对目标项目具有 Maintainer/Owner 访问权限。请参见 集中式 webhook 注册 token。

#第 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 设置为项目 URL，并添加 git_provider.url，其值为 GitLab 实例的 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

应用该配置：

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 注册 controller 会监视它并注册一个 GitLab project 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。controller 会创建或更新 GitLab webhook，配置如下：

• URL：公开的 PAC webhook URL
• Secret token：spec.git_provider.webhook_secret 引用的 webhook.secret 值
• 事件：push、tag push、comments 和 merge requests
• SSL verification：默认启用

controller 会将 GitLab hook ID 记录在 pac.tekton.alauda.io/webhook-managed-ref 中。如果之后 PAC webhook URL 发生变化，controller 会按 ID 更新已记录的 hook，而不是为同一项目创建重复的 hook。

若要从自动 webhook 注册中排除某个 Repository，请向该 Repository 的 metadata 添加以下 label：

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

#手动回退

如果无法使用自动注册，或者自动注册已被禁用，请手动注册 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 操作。返回 200 响应表示 controller 已收到并接受该事件。

#第 5 步：添加 PipelineRun 并触发它

在仓库的 .tekton/ 下添加一个 PipelineRun manifest 并推送。PAC 会读取触发事件所在分支上的文件，将 annotations 与事件进行匹配，并在该 namespace 中创建一个 PipelineRun。

有关文件布局和 annotation 语法，请参见 在 Git 中定义 PipelineRun；有关自动触发和基于评论的触发，请参见 触发 PAC Pipelines。

#验证

当 Git 事件到达后，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 状态。

#故障排查

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

#下一步

• 在 Git 中定义 PipelineRun — 在 .tekton/ 下定义和演进 pipelines。
• 触发 PAC Pipelines — 自动事件和评论命令。
• 高级 Repository 配置 — 并发、参数、自定义设置。
• 配置自定义证书 — 适用于使用私有 CA 的自托管 GitLab。