#配置 GitLab Repository

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

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

本页使用 manifest 和 GitLab Web UI。有关 CLI 工作流，请参见 tkn pac Command Reference。

#前提条件

• 已部署 PAC component，并对 GitLab 暴露；参见 Manage PAC Component。
• PAC webhook URL；参见 Get the PAC Webhook URL。
• 对 GitLab project 具有 Maintainer 访问权限（添加 webhook 所必需）。
• 一个目标 Kubernetes namespace，用于存放 Repository 资源及其 PipelineRun。
• 该 namespace 的 kubectl 访问权限。

#步骤 1：创建 GitLab Access Token

PAC 需要一个 token 来读取 project 元数据、发布 merge request 评论以及更新 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

应用该资源：

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 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。

#故障排除

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

#后续步骤

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