#配置 GitLab 仓库

本指南说明如何配置 GitLab 仓库以配合 PAC 使用，实现从 GitLab 事件触发流水线。

#前提条件

在配置 GitLab 仓库之前，请确保您已具备：

• 已部署并运行 PAC 组件（参见管理 PAC 组件）
• PAC controller 已暴露且可访问（通过 Ingress 或 NodePort）
• 已安装带有 pac 插件的 tkn CLI
• 拥有仓库级别的 GitLab 管理权限
• 拥有具备相应权限的 GitLab 个人访问令牌（Personal Access Token）

#概述

推荐使用 tkn pac create repo 命令来配置 GitLab 仓库。该命令自动完成整个配置流程：

1. 在 Kubernetes 集群中创建 Repository CR
2. 自动配置 GitLab webhook
3. 创建包含 GitLab 凭据的 Kubernetes Secret
4. 在仓库中生成基础的 .tekton/pipelinerun.yaml 模板

#第 1 步：安装 tkn pac 插件

确保已安装 tkn pac 插件：

tkn pac version

如果未安装，请参见 tkn pac 命令参考 中的安装指南。

#第 2 步：准备 GitLab 访问令牌

您需要一个具备以下权限范围的 GitLab 个人访问令牌：

• api：完整的 API 访问权限

#创建个人访问令牌

1. 进入 GitLab → 用户设置 → 访问令牌（或项目设置 → 访问令牌，针对项目令牌）
2. 创建新令牌，配置如下：
   • 名称：PAC Integration（或任何描述性名称）
   • 权限范围：选择 api
   • 过期时间：根据需要设置（可选）
3. 点击 创建个人访问令牌
4. 立即复制令牌 — 令牌只显示一次

#安全存储令牌

请将令牌保存在安全位置，后续运行 tkn pac create repo 时需要使用。

安全最佳实践：建议使用项目令牌替代个人令牌，以实现更细粒度的访问控制。

#第 3 步：获取 PAC Controller URL

配置仓库前，您需要获取 PAC controller 的 URL。GitLab 会通过该 URL 向 PAC 发送 webhook 事件。

#方法 1：查询 Ingress（如果已配置）

检查 PAC controller 是否通过 Ingress 暴露（将 <pac-namespace> 替换为您的 PAC 命名空间，默认是 tekton-pipelines）：

kubectl get ingress -n <pac-namespace> | grep pipelines-as-code

示例输出（如果配置了 Ingress）：

NAME                  CLASS    HOSTS              ADDRESS        PORTS   AGE
pipelines-as-code     nginx    pac.example.com    192.168.1.10   80      5m

如果找到，获取 Ingress 主机名：

kubectl get ingress pipelines-as-code -n <pac-namespace> -o jsonpath='{.spec.rules[0].host}'

示例输出：

pac.example.com

controller URL 为：

• HTTP: http://<ingress-host>
• HTTPS: https://<ingress-host>

#方法 2：查询 NodePort 服务（如果已配置）

检查 PAC controller 是否通过 NodePort 暴露（将 <pac-namespace> 替换为您的 PAC 命名空间，默认是 tekton-pipelines）：

kubectl get svc -n <pac-namespace> pipelines-as-code-controller-nodeport

示例输出（如果配置了 NodePort）：

NAME                                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
pipelines-as-code-controller-nodeport    NodePort   10.96.123.45    <none>        8080:30080/TCP   5m

如果找到，获取 NodePort 和节点 IP：

# 设置 PAC 命名空间（默认：tekton-pipelines）
PAC_NAMESPACE="tekton-pipelines"

# 获取 NodePort
NODEPORT=$(kubectl get service -n ${PAC_NAMESPACE} pipelines-as-code-controller-nodeport -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

# 获取节点 IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "PAC Controller URL: http://${NODE_IP}:${NODEPORT}"

示例输出：

PAC Controller URL: http://192.168.1.100:30080

#方法 3：查询 LoadBalancer 服务（如果已配置）

检查 PAC controller 是否通过 LoadBalancer 暴露（将 <pac-namespace> 替换为您的 PAC 命名空间，默认是 tekton-pipelines）：

kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer

示例输出（如果配置了 LoadBalancer）：

NAME                                      TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
pipelines-as-code-controller-lb          LoadBalancer   10.96.123.45    192.168.1.200   8080:30080/TCP   5m

如果找到，获取服务名称和外部 IP：

# 先获取服务名称
SERVICE_NAME=$(kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer | awk '{print $1}')

# 获取外部 IP
kubectl get svc -n <pac-namespace> ${SERVICE_NAME} -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

示例输出：

192.168.1.200

#tkn pac 的自动检测

tkn pac create repo 命令会自动检测 controller URL，依次检查：

1. Ingress 资源
2. LoadBalancer 服务
3. NodePort 服务

如果自动检测失败，您可以在提示时手动输入 URL。

#如果找不到 URL

如果以上方法均无效或您无权限查询集群资源：

1. 联系您的 PAC 管理员 获取 PAC controller URL
2. 管理员可使用管理 PAC 组件 中的方法查询
3. URL 格式通常为：http://<host-or-ip>:<port> 或 https://<host-or-ip>

#第 4 步：使用 tkn pac 配置仓库

#进入您的仓库目录

克隆或进入您的 GitLab 仓库目录：

cd /path/to/your/gitlab-repo

#运行 tkn pac create repo

重要：请在您的 GitLab 仓库目录下运行该命令，.tekton 目录将创建在当前工作目录。

cd /path/to/your/gitlab/repo
tkn pac create repo --pac-namespace tekton-pipelines

注意：如果 PAC 安装在其他命名空间，请调整 --pac-namespace 参数。将 tekton-pipelines 替换为您实际部署 PAC 的命名空间。该参数指定 PAC controller 所在命名空间（默认：tekton-pipelines）。

#交互式配置

命令会提示您输入以下信息：

#1. Git 仓库 URL

? Enter the Git repository URL: 

• 默认：自动检测当前目录的 git 远程地址
• 格式：https://gitlab.com/username/repo 或 git@gitlab.com:username/repo
• 操作：按回车使用默认，或输入其他 URL

#2. Pipeline 运行命名空间

? Enter the namespace where the pipeline should run (default: default): 

• 默认：default
• 说明：PipelineRun 创建所在的 Kubernetes 命名空间
• 操作：输入您希望使用的命名空间（如 project-pipelines），或按回车使用默认

重要：

• 命名空间必须存在，PAC 才能在其中创建 PipelineRun

• 如果不存在，请先创建：

  kubectl create namespace <your-namespace>

  示例：

  kubectl create namespace project-pipelines

• 建议使用专用命名空间（如 project-pipelines），避免使用 default

• 命名空间需具备 PAC 创建资源的 RBAC 权限

#3. GitLab 项目 ID

? Enter the GitLab project ID: 

• 查找方法：
  • 进入 GitLab 项目 → 设置 → 常规
  • 在“项目信息”中找到“项目 ID”
  • 或使用 API 查询：curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/projects?search=<repo-name>"

#4. PAC Controller URL

? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 

• 默认：自动从集群资源检测
• 操作：
  • 自动检测正确时，按回车
  • 未检测到时，手动输入 URL
  • 如果不知道 URL：参见上文第 3 步：获取 PAC Controller URL 或联系管理员

#5. Webhook Secret

? Enter the webhook secret (default: auto-generated): 

• 默认：自动生成的随机字符串
• 说明：用于验证 GitLab webhook 请求的密钥
• 操作：按回车使用默认，或输入自定义密钥

安全提示：请妥善保管该密钥，存储于 Kubernetes Secret 中。

#6. GitLab 访问令牌

? Enter the GitLab access token: 

• 说明：第 2 步创建的个人访问令牌
• 操作：粘贴令牌

#7. GitLab API URL

? Enter the GitLab API URL (default: https://gitlab.com): 

• 默认：https://gitlab.com（适用于 GitLab.com）
• 自托管 GitLab：请输入您的 GitLab 实例 URL，例如 https://gitlab.example.com
• 操作：GitLab.com 按回车，或输入自托管实例 URL

#交互示例

? Enter the Git repository URL: https://gitlab.com/myuser/myproject
? Enter the namespace where the pipeline should run (default: project-pipelines): 
? Enter the GitLab project ID: 12345678
? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 
? Enter the webhook secret (default: auto-generated): 
? Enter the GitLab access token: glpat-xxxxxxxxxxxxxxxxxxxx
? Enter the GitLab API URL (default: https://gitlab.com): 

#第 5 步：验证配置

#检查 Repository CR

首先确认您指定的命名空间（创建 Repository CR 时使用的命名空间）。如果忘记，可以列出所有 Repository CR：

kubectl get repositories --all-namespaces

示例输出：

NAMESPACE          NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
project-pipelines  my-repo    https://gitlab.com/user/repo     True        Succeeded

然后验证 Repository CR 是否在您的命名空间中创建：

kubectl get repositories -n <your-namespace>

示例输出：

NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
my-repo    https://gitlab.com/user/repo     True        Succeeded

查看 Repository CR 详情：

先从列表中获取仓库名称，然后查看详情：

kubectl get repository <repo-name> -n <your-namespace> -o yaml

将 <repo-name> 替换为实际仓库名（如 my-repo）。

示例输出（简略）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"

#检查 GitLab Webhook

1. 进入 GitLab 项目 → 设置 → Webhooks
2. 验证是否创建了 webhook，包含：
   • URL：您的 PAC controller URL
   • 触发事件：Push 事件、合并请求事件、评论
   • Secret token：您配置的 webhook 密钥

#检查 Kubernetes Secret

使用 tkn pac create repo 时，会自动创建包含 GitLab 凭据的 Secret。验证 Secret：

kubectl get secrets -n <your-namespace>

示例输出：

NAME                          TYPE     DATA   AGE
my-repo                       Opaque   2      2m

查看 Secret 详情：

kubectl get secret <secret-name> -n <your-namespace> -o yaml

将 <secret-name> 替换为实际 Secret 名（通常与仓库名相同）。

示例输出（值为 base64 编码）：

apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: project-pipelines
data:
  provider.token: <base64-encoded-gitlab-token>
  webhook.secret: <base64-encoded-webhook-secret>

Secret 包含：

• provider.token：您的 GitLab 个人访问令牌
• webhook.secret：Webhook 验证密钥

#检查生成的模板

确认仓库中已生成 .tekton/pipelinerun.yaml 模板：

cat .tekton/pipelinerun.yaml

示例输出：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: simple-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from Pipelines as Code!"

#第 6 步：测试配置

#测试 Webhook 连接

您可以在 GitLab 测试 webhook：

1. 进入 GitLab 项目 → 设置 → Webhooks
2. 找到您的 PAC webhook
3. 点击 测试 → Push 事件
4. 检查 webhook 响应

#触发测试流水线

提交一个简单的更改以触发流水线：

echo "test" >> README.md
git add README.md
git commit -m "Test PAC integration"
git push origin main

检查是否创建了 PipelineRun：

kubectl get pipelineruns -n <your-namespace>

示例输出：

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   1 minute ago   25s        Succeeded

#手动配置（备选）

如果您希望手动配置或需要更细粒度控制，可以分别创建 Repository CR 和配置 webhook。

#手动创建 Repository CR

创建文件 repository.yaml：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/myuser/myproject"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

应用 CR：

kubectl apply -f repository.yaml

示例输出：

repository.pipelinesascode.tekton.dev/my-repo created

#创建 GitLab Secret

创建包含 GitLab 令牌的 Secret：

kubectl create secret generic gitlab-secret \
  --from-literal=token=glpat-xxxxxxxxxxxxxxxxxxxx \
  -n project-pipelines

示例输出：

secret/gitlab-secret created

#创建 Webhook Secret

kubectl create secret generic webhook-secret \
  --from-literal=secret=your-webhook-secret \
  -n project-pipelines

示例输出：

secret/webhook-secret created

#手动配置 GitLab Webhook

1. 进入 GitLab 项目 → 设置 → Webhooks
2. 添加新 webhook：
   • URL：http://pac.example.com
   • Secret token：上面创建的 webhook secret
   • 触发事件：选择“Push 事件”和“合并请求事件”
3. 点击 添加 webhook

#使用私有仓库

PAC 支持私有 GitLab 仓库。有关私有仓库的身份验证配置，请参见为私有仓库配置身份验证指南。

该指南涵盖所有 Git 提供商通用的身份验证方法，包括：

• 个人访问令牌（PAT）身份验证
• SSH 密钥身份验证
• 验证步骤和故障排查

#自定义证书的接口配置

如果您的 GitLab 实例使用自签名证书或自定义 CA 证书，您需要配置 PAC 信任这些证书。详见配置自定义证书指南。

该指南涵盖：

• 创建包含 CA 证书的 ConfigMap
• 在 PAC controller Pod 中挂载证书
• 配置 Git 使用自定义证书
• 验证和故障排查步骤

#故障排查

#检查 Repository CR 是否未创建

查看错误信息：

kubectl describe repository <repo-name> -n <your-namespace>

示例输出（简略）：

Name:         my-repo
Namespace:    project-pipelines
Status:       Ready
Events:
  Type    Reason   Age   From     Message
  ----    ------   ----  ----     -------
  Normal  Ready    5m    pac      Repository validated

#检查 webhook 是否未配置

如果 webhook 未自动创建：

1. 确认 GitLab 令牌具有 api 权限
2. 检查令牌有效性：curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"
3. 手动创建 webhook（参见手动配置部分）

#检查 webhook 事件未接收

1. 查看 PAC controller 日志：

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

示例输出：

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing webhook event","repository":"my-repo","namespace":"project-pipelines"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun created","pipelineRun":"simple-pipeline-xxxxx"}

2. 确认 GitLab 能访问 webhook URL
3. 检查 webhook secret 在 GitLab 和 Repository CR 中是否一致

#检查 PipelineRun 未创建

1. 查看 Repository CR：

   kubectl get repository <repo-name> -n <your-namespace> -o yaml

示例输出（简略）：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines

2. 查看 PAC controller 日志是否有错误
3. 确认仓库中存在 .tekton/pipelinerun.yaml
4. 检查命名空间权限设置

#检查私有仓库访问问题

1. 确认令牌权限：确保令牌具备 api 权限
2. 检查 Secret 是否存在：验证认证 Secret 是否存在于命名空间
3. 检查 Repository CR：确保 Secret 引用正确
4. 查看 PAC 日志：查找认证相关错误

详情请参见为私有仓库配置身份验证。

#检查证书问题

1. 确认证书挂载：检查证书是否挂载到 Pod
2. 检查证书有效性：确保证书未过期
3. 确认 Git 配置：检查 Git 是否配置使用该证书
4. 查看日志：查找 PAC controller 日志中的 SSL/证书错误

详情请参见配置自定义证书。

#后续步骤

• 为私有仓库配置身份验证 - 配置私有仓库身份验证
• 配置自定义证书 - 配置自定义 CA 证书
• 维护流水线代码 - 学习如何在仓库中定义流水线
• 触发流水线 - 了解不同的触发方式
• 常见问题 - 故障排查指南