配置 GitLab 仓库

适用于普通用户

本指南适用于普通用户，用于为 PAC 集成配置其 GitLab 仓库。如果你需要了解 PAC controller URL 或 webhook 配置，请参阅下面的查询说明。

重要：在本文档中，我们会使用两个不同的命名空间：

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

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

本指南说明如何配置 GitLab 仓库以配合 PAC 使用，从而使 pipeline 可以由 GitLab 事件触发。

前提条件概览第 1 步：安装 tkn pac 插件第 2 步：准备 GitLab Access Token 创建 Personal Access Token 安全保存 token 第 3 步：获取 PAC Controller URL 方法 1：查询 Ingress（如果已配置）方法 2：查询 NodePort Service（如果已配置）方法 3：查询 LoadBalancer Service（如果已配置）由 tkn pac 自动检测如果找不到 URL 第 4 步：使用 tkn pac 配置仓库进入你的仓库运行 tkn pac create repo 交互式配置 1. Git 仓库 URL 2. 运行 Pipeline 的命名空间 3. GitLab Project ID 4. PAC Controller URL 5. Webhook Secret 6. GitLab Access Token 7. GitLab API URL 交互式会话示例第 5 步：验证配置检查 Repository CR 检查 GitLab Webhook 检查 Kubernetes Secret 检查生成的模板第 6 步：测试配置测试 webhook 连接触发测试 pipeline 手动配置（可选）手动创建 Repository CR 创建 GitLab Secret 创建 Webhook Secret 手动配置 GitLab Webhook 使用私有仓库与自定义证书交互故障排除检查 Repository CR 是否未创建检查 webhook 是否未配置检查是否未收到 webhook 事件检查是否未创建 PipelineRuns 检查私有仓库访问问题检查证书问题下一步

前提条件

在配置 GitLab 仓库之前，请确保你已具备以下条件：

PAC 组件已部署并运行（参见管理 PAC 组件）
PAC controller 已暴露并可访问（通过 Ingress 或 NodePort）
已安装 tkn CLI 及 pac 插件
具有 repo-scope 管理员访问权限的 GitLab 仓库
具备相应权限范围的 GitLab Personal Access Token

概览

tkn pac create repo 命令是为 PAC 配置 GitLab 仓库的推荐方式。它会自动完成整个设置流程：

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

第 1 步：安装 tkn pac 插件

确保你已经安装了 tkn pac 插件：

tkn pac version

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

第 2 步：准备 GitLab Access Token

你需要一个具有以下权限范围的 GitLab Personal Access Token：

api：完整 API 访问权限

创建 Personal Access Token

转到 GitLab → User Settings → Access Tokens（如果是 project token，则转到 Project Settings → Access Tokens）
创建一个新 token，并设置：
- Name：PAC Integration（或任意具有描述性的名称）
- Scopes：选择 api
- Expiration date：按需设置（可选）
单击 Create personal access token
立即复制该 token - 它不会再次显示

安全保存 token

将 token 保存到安全位置。运行 tkn pac create repo 时需要使用它。

安全最佳实践：为了更好的访问控制，建议使用 project token 而不是 personal token。

第 3 步：获取 PAC Controller URL

在配置仓库之前，你需要 PAC controller URL。GitLab 会使用该 URL 将 webhook 事件发送到 PAC。

查询 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 host：

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 Service（如果已配置）

检查 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 Service（如果已配置）

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

如果找到了，获取 service 名称和外部 IP：

# 先获取 service 名称
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 service
NodePort service

如果自动检测失败，你可以在提示时手动输入 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 参数。如果你将 PAC 部署在其他命名空间中，请将 tekton-pipelines 替换为实际的 PAC 命名空间。--pac-namespace 参数用于指定 PAC controller 的部署位置（默认值：tekton-pipelines）。

交互式配置

命令将提示你输入以下信息：

1. Git 仓库 URL

? Enter the Git repository URL:

默认值：自动从当前目录的 git remote 检测
格式：https://gitlab.com/username/repo 或 git@gitlab.com:username/repo
操作：按 Enter 使用默认值，或输入其他 URL

2. 运行 Pipeline 的命名空间

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

默认值：default
说明：创建 PipelineRuns 的 Kubernetes 命名空间
操作：输入你希望使用的命名空间（例如 project-pipelines），或按 Enter 使用 default

重要：

在 PAC 能够在其中创建 PipelineRuns 之前，该命名空间必须已经存在

如果命名空间不存在，请先创建它：

kubectl create namespace <your-namespace>

示例：

kubectl create namespace project-pipelines

建议使用类似 project-pipelines 的专用命名空间，而不是 default
该命名空间必须具备 RBAC 权限，以便 PAC 创建资源

3. GitLab Project ID

? Enter the GitLab project ID:

如何查找：
- 转到你的 GitLab 项目 → Settings → General
- 在 "Project information" 下找到 "Project 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):

默认值：从集群资源自动检测
操作：
- 如果自动检测正确，按 Enter
- 如果未检测到，请手动输入 URL
- 如果你不知道 URL：请参阅上面的第 3 步：获取 PAC Controller URL 查询命令，或联系你的 PAC 管理员

5. Webhook Secret

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

默认值：自动生成的随机字符串
说明：用于验证来自 GitLab 的 webhook 请求的 secret
操作：按 Enter 使用默认值，或输入自定义 secret

安全性：请妥善保管该 secret。它会存储在 Kubernetes Secret 中。

6. GitLab Access Token

? Enter the GitLab access token:

说明：在第 2 步中创建的 Personal Access Token
操作：粘贴你的 token

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 直接按 Enter，或输入你的实例 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 详情：

先从上面的列表中获取 repository 名称，然后查看详情：

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

将 <repo-name> 替换为列表中的实际 repository 名称（例如 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 项目 → Settings → Webhooks
验证 webhook 是否已创建，并确认以下信息：
- URL：你的 PAC controller URL
- Trigger：Push events、Merge request events、Comments
- Secret token：你配置的 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 名称（通常与 repository 名称相同）。

示例输出（值已进行 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 personal access token
webhook.secret：webhook 验证 secret

检查生成的模板

验证仓库中是否已创建 .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 项目 → Settings → Webhooks
找到你的 PAC webhook
单击 Test → Push events
检查 webhook 响应

触发测试 pipeline

创建一个简单的 commit 来触发 pipeline：

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 token 创建一个 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 项目 → Settings → Webhooks
添加一个新的 webhook：
- URL：http://pac.example.com
- Secret token：上面的 webhook secret
- Trigger：选择 "Push events" 和 "Merge request events"
单击 Add webhook

使用私有仓库

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

本指南涵盖适用于所有 Git provider 的身份验证方法，包括：

Personal Access Token (PAT) 身份验证
SSH key 身份验证
验证步骤和故障排除

与自定义证书交互

如果你的 GitLab 实例使用自签名证书或自定义 CA 证书，则需要配置 PAC 以信任这些证书。有关详细说明，请参阅配置自定义证书指南。

本指南涵盖：

使用 CA 证书创建 ConfigMaps
在 PAC controller pods 中挂载证书
配置 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 token 是否具有 api 权限范围
检查 token 是否有效：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
检查 GitLab 和 Repository CR 中的 webhook secret 是否一致

检查是否未创建 PipelineRuns

检查 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
检查命名空间权限

检查私有仓库访问问题

验证 token 权限：确保 token 具有 api 权限范围
检查 secret 是否存在：验证认证 secret 是否存在于该命名空间中
检查 Repository CR：确保正确引用了 secret
检查 PAC 日志：在 controller 日志中查找认证错误

更多详情，请参阅为私有仓库配置身份验证。

检查证书问题

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

更多详情，请参阅配置自定义证书。

下一步

为私有仓库配置身份验证 - 为私有仓库配置身份验证
配置自定义证书 - 配置自定义 CA 证书
维护 Pipeline Code - 了解如何在仓库中定义 pipeline
触发 pipeline - 了解不同的触发方式
常见问题 - 故障排除指南

#配置 GitLab 仓库

#目录

#前提条件

#概览

#第 1 步：安装 tkn pac 插件

#第 2 步：准备 GitLab Access Token

#创建 Personal Access Token

#安全保存 token

#第 3 步：获取 PAC Controller URL

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

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

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

#由 tkn pac 自动检测

#如果找不到 URL

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

#进入你的仓库

#运行 tkn pac create repo

#交互式配置

#1. Git 仓库 URL

#2. 运行 Pipeline 的命名空间

#3. GitLab Project ID

#4. PAC Controller URL

#5. Webhook Secret

#6. GitLab Access Token

#7. GitLab API URL

#交互式会话示例

#第 5 步：验证配置

#检查 Repository CR

#检查 GitLab Webhook

#检查 Kubernetes Secret

#检查生成的模板

#第 6 步：测试配置

#测试 webhook 连接

#触发测试 pipeline

#手动配置（可选）

#手动创建 Repository CR

#创建 GitLab Secret

#创建 Webhook Secret

#手动配置 GitLab Webhook

#使用私有仓库

#与自定义证书交互

#故障排除

#检查 Repository CR 是否未创建

#检查 webhook 是否未配置

#检查是否未收到 webhook 事件

#检查是否未创建 PipelineRuns

#检查私有仓库访问问题

#检查证书问题

#下一步

配置 GitLab 仓库

目录

前提条件

概览

第 1 步：安装 tkn pac 插件

第 2 步：准备 GitLab Access Token

创建 Personal Access Token

安全保存 token

第 3 步：获取 PAC Controller URL

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

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

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

由 tkn pac 自动检测

如果找不到 URL

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

进入你的仓库

运行 tkn pac create repo

交互式配置

1. Git 仓库 URL

2. 运行 Pipeline 的命名空间

3. GitLab Project ID

4. PAC Controller URL

5. Webhook Secret

6. GitLab Access Token

7. GitLab API URL

交互式会话示例

第 5 步：验证配置

检查 Repository CR

检查 GitLab Webhook

检查 Kubernetes Secret

检查生成的模板

第 6 步：测试配置

测试 webhook 连接

触发测试 pipeline

手动配置（可选）

手动创建 Repository CR

创建 GitLab Secret

创建 Webhook Secret

手动配置 GitLab Webhook

使用私有仓库

与自定义证书交互

故障排除

检查 Repository CR 是否未创建

检查 webhook 是否未配置

检查是否未收到 webhook 事件

检查是否未创建 PipelineRuns

检查私有仓库访问问题

检查证书问题

下一步