Configure GitLab Repository

For Regular Users

本指南适用于普通用户配置其 GitLab 仓库以集成 PAC。如果您需要有关 PAC controller URL 或 webhook 配置的信息，请参见下方的查询说明。

重要提示：本文档中使用了两个不同的命名空间：

<pac-namespace>：部署 PAC 组件（controller、watcher、webhook）的命名空间。默认是 tekton-pipelines，但可以通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 自定义。
<your-namespace> 或 Pipeline 命名空间：创建 PipelineRun 的命名空间。在创建 Repository CR 时指定，可以是集群中的任意命名空间。

请将这些占位符替换为您实际的命名空间名称。

本指南介绍如何配置 GitLab 仓库以配合 PAC 使用，实现基于 GitLab 事件触发流水线。

前提条件

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

已部署并运行 PAC 组件（参见管理 PAC 组件）
PAC controller 已暴露且可访问（通过 Ingress 或 NodePort）
已安装带有 pac 插件的 tkn CLI
拥有仓库范围的 GitLab 管理权限
拥有带有适当权限范围的 GitLab 个人访问令牌

概述

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

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

第 1 步：安装 tkn pac 插件

确保您已安装 tkn pac 插件：

tkn pac version

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

第 2 步：准备 GitLab 访问令牌

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

api：完整 API 访问权限

创建个人访问令牌

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

安全存储令牌

请将令牌妥善保存，后续运行 tkn pac create repo 时需要使用。

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

第 3 步：获取 PAC Controller URL

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

查询 PAC Controller URL

如果您不知道 PAC controller URL，可以尝试以下命令查询。如果命令无结果，请联系您的 PAC 管理员。

方法 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，检测顺序为：

Ingress 资源
LoadBalancer 服务
NodePort 服务

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

如果找不到 URL

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

联系您的 PAC 管理员 获取 PAC controller URL
管理员可使用管理 PAC 组件中的方法查询
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-namespace 参数指定 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
- 如果不知道 URL：参见上方第 3 步：获取 PAC Controller URL 或联系 PAC 管理员

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

进入 GitLab 项目 → 设置 → Webhooks
确认已创建 webhook，且：
- URL：为您的 PAC controller URL
- 触发事件：Push 事件、合并请求事件、评论事件
- 密钥令牌：您配置的 webhook secret

检查 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：

进入 GitLab 项目 → 设置 → Webhooks
找到您的 PAC webhook
点击测试 → Push events
查看 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

进入 GitLab 项目 → 设置 → Webhooks
添加新 webhook：
- URL：http://pac.example.com
- 密钥令牌：上述 webhook secret
- 触发事件：选择“Push events”和“Merge request events”
点击 添加 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 未自动创建：

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

检查 webhook 事件未接收

查看 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"}

确认 GitLab 可访问 webhook URL
检查 webhook secret 在 GitLab 和 Repository CR 中是否一致

检查 PipelineRun 未创建

查看 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

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

检查私有仓库访问问题

确认令牌权限：确保令牌具有 api 权限
检查 Secret 是否存在：确认认证 Secret 在命名空间中存在
检查 Repository CR：确保 Secret 被正确引用
查看 PAC 日志：检查 controller 日志中是否有认证错误

详情请参见为私有仓库配置认证。

检查证书问题

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

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

后续步骤

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

#Configure GitLab Repository

#目录

#前提条件

#概述

#第 1 步：安装 tkn pac 插件

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

#创建个人访问令牌

#安全存储令牌

#第 3 步：获取 PAC Controller URL

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

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

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

#tkn pac 自动检测

#如果找不到 URL

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

#进入您的仓库目录

#运行 tkn pac create repo

#交互式配置

#1. Git 仓库 URL

#2. Pipeline 运行命名空间

#3. GitLab 项目 ID

#4. PAC Controller URL

#5. Webhook Secret

#6. GitLab 访问令牌

#7. GitLab API URL

#交互示例

#第 5 步：验证配置

#查看 Repository CR

#检查 GitLab Webhook

#检查 Kubernetes Secret

#检查生成的模板

#第 6 步：测试配置

#测试 Webhook 连接

#触发测试流水线

#手动配置（备选）

#手动创建 Repository CR

#创建 GitLab Secret

#创建 Webhook Secret

#手动配置 GitLab Webhook

#使用私有仓库

#自定义证书支持

#故障排查

#检查 Repository CR 是否未创建

#检查 webhook 是否未配置

#检查 webhook 事件未接收

#检查 PipelineRun 未创建

#检查私有仓库访问问题

#检查证书问题

#后续步骤

Configure GitLab Repository

目录

前提条件

概述

第 1 步：安装 tkn pac 插件

第 2 步：准备 GitLab 访问令牌

创建个人访问令牌

安全存储令牌

第 3 步：获取 PAC Controller URL

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

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

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

tkn pac 自动检测

如果找不到 URL

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

进入您的仓库目录

运行 tkn pac create repo

交互式配置

1. Git 仓库 URL

2. Pipeline 运行命名空间

3. GitLab 项目 ID

4. PAC Controller URL

5. Webhook Secret

6. GitLab 访问令牌

7. GitLab API URL

交互示例

第 5 步：验证配置

查看 Repository CR

检查 GitLab Webhook

检查 Kubernetes Secret

检查生成的模板

第 6 步：测试配置

测试 Webhook 连接

触发测试流水线

手动配置（备选）

手动创建 Repository CR

创建 GitLab Secret

创建 Webhook Secret

手动配置 GitLab Webhook

使用私有仓库

自定义证书支持

故障排查

检查 Repository CR 是否未创建

检查 webhook 是否未配置

检查 webhook 事件未接收

检查 PipelineRun 未创建

检查私有仓库访问问题

检查证书问题

后续步骤