配置 GitLab 仓库

For Regular Users

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

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

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

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

本指南说明如何配置 GitLab 仓库以与 PAC 协同工作，从而使 pipelines 能够由 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. Pipelines 命名空间 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 组件（参见 Manage PAC Component）
已暴露且可访问的 PAC controller（通过 Ingress 或 NodePort）
已安装 tkn CLI 及 pac 插件
具有 repo-scope admin 访问权限的 GitLab 仓库
具有适当 scopes 的 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 Command Reference 中的安装指南。

第 2 步：准备 GitLab Access Token

你需要一个具有以下 scopes 的 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。

Query PAC Controller URL

如果你不知道 PAC controller URL，可以尝试使用以下命令进行查询。如果这些命令没有返回结果，请联系你的 PAC administrator。

方法 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 和 node IP：

# Set your PAC namespace (default: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

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

# Get Node 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：

# Get the service name first
SERVICE_NAME=$(kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer | awk '{print $1}')

# Get the external 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 resources
LoadBalancer services
NodePort services

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

如果无法找到 URL

如果以上方法均无效，或者你没有查询集群资源的权限：

联系你的 PAC administrator 获取 PAC controller URL
administrator 可以使用 Manage PAC Component 中的方法查找
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. Pipelines 命名空间

? 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
该命名空间必须具有允许 PAC 创建资源的 RBAC 权限

3. GitLab Project ID

? Enter the GitLab project ID:

如何查找：
- 前往你的 GitLab project → 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 administrator

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 project → 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 project → Settings → Webhooks
找到你的 PAC webhook
点击 Test → Push events
检查 webhook 响应

触发测试 pipeline

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

使用私有仓库

PAC 支持私有 GitLab 仓库。如需为私有仓库配置认证，请参阅 Configure Authentication for Private Repositories 指南。

本指南涵盖适用于所有 Git provider 的认证方式，包括：

Personal Access Token (PAT) 认证
SSH key 认证
验证步骤与故障排查

与自定义证书交互

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

本指南涵盖：

创建包含 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 scope
检查 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  # Replace <pac-namespace> with your actual namespace (default: 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"}

验证 webhook URL 可从 GitLab 访问
检查 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 scope
检查 secret 是否存在：验证认证 secret 是否存在于该命名空间中
查看 Repository CR：确保正确引用了 secret
检查 PAC 日志：在 controller 日志中查找认证错误

更多详情请参阅 Configure Authentication for Private Repositories。

检查证书问题

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

更多详情请参阅 Configure Custom Certificates。

后续步骤

Configure Authentication for Private Repositories - 为私有仓库配置认证
Configure Custom Certificates - 配置自定义 CA 证书
Maintain Pipeline Code - 了解如何在仓库中定义 pipelines
Trigger Pipelines - 了解不同的触发方式
Common Issues - 故障排查指南

#配置 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. Pipelines 命名空间

#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. Pipelines 命名空间

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

检查私有仓库访问问题

检查证书问题

后续步骤