#配置 GitLab 仓库

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

GitLab 使用 Webhook 模式。每个仓库都配置一个 GitLab access token 和一个项目 webhook。

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

#前提条件

• PAC 组件已部署并暴露给 GitLab；请参阅 管理 PAC 组件。
• PAC webhook URL；请参阅 获取 PAC Webhook URL。
• 对 GitLab 项目拥有 Maintainer 访问权限（用于添加 webhook）。
• 一个目标 Kubernetes 命名空间，用于存放 Repository 资源及其 PipelineRun。
• 对该命名空间的 kubectl 访问权限。

#步骤 1：创建 GitLab Access Token

PAC 需要一个 token 来读取项目元数据、发布 merge request 评论以及更新 commit status。Personal Access Token 和 Project Access Token 都可以使用。

1. 在 GitLab 中，打开项目或用户的 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 设置为项目 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

应用该配置：

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 项目，然后进入 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 会从事件发生时所在的分支读取该文件，将注解与事件进行匹配，并在该命名空间中创建一个 PipelineRun。

有关文件布局和注解语法，请参阅 在 Git 中定义 PipelineRun；有关 PAC 响应的 Git 操作，请参阅 触发 Pipeline。

#验证

当 Git 事件到达后，PAC 会在 Repository 的命名空间中创建一个 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。

#故障排查

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

#下一步

• 在 Git 中定义 PipelineRun — 在 .tekton/ 下定义并演进 pipeline。
• 触发 Pipeline — push、merge request 和 comment 驱动的触发方式。
• 高级 Repository 配置 — 并发、参数、自定义设置。
• 配置自定义证书 — 适用于带有私有 CA 的自托管 GitLab。