常见问题

适用于所有用户

本故障排查指南涵盖了 管理员(组件部署、配置)和 普通用户(仓库设置、pipeline 执行)可能遇到的问题。

重要:在本文档中,我们使用两个不同的 namespace:

  • <pac-namespace>:部署 PAC 组件(controller、watcher、webhook)的 namespace。默认值为 tekton-pipelines,但可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义。
  • <namespace>:创建 PipelineRuns 的 namespace。在创建 Repository CR 时指定,可以是集群中的任意 namespace。

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

本文档提供了在使用 Pipelines-as-Code(PAC)时遇到的常见问题的故障排查步骤。

开始之前

在排查具体问题之前,请先验证以下基础项:

1. 检查 PAC 组件是否正在运行

验证所有 PAC pod 都在运行(将 <pac-namespace> 替换为你的 PAC namespace,默认为 tekton-pipelines):

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

输出示例(所有 pod 都应为 Running):

NAME                                          READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-769bf5c88c-xxxxx  1/1     Running   0          113d
pipelines-as-code-watcher-546d6cd86d-xxxxx     1/1     Running   15         113d
pipelines-as-code-webhook-5fcd94db5b-xxxxx     1/1     Running   0          113d

2. 确定你的 namespaces

获取 PAC namespace(PAC 组件部署所在位置):

kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o jsonpath='{.spec.targetNamespace}'

如果命令失败或返回为空,请使用默认值:tekton-pipelines

获取 Pipeline namespace(创建 PipelineRuns 的位置):

kubectl get repository -A

这将显示所有 Repository CR 及其 namespace。namespace 列显示 PipelineRuns 将在哪个 namespace 中创建。

3. 获取资源名称

获取 pod 名称:

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

获取 Repository CR 名称:

kubectl get repository -n <namespace>

获取 PipelineRun 名称:

kubectl get pipelinerun -n <namespace>

4. 本文档中使用的常见占位符

  • <pac-namespace>:PAC 部署所在的 namespace(默认:tekton-pipelines)
  • <namespace>:PipelineRun 所在的 namespace(因 repository 而异)
  • <repo-name>:Repository CR 名称(使用 kubectl get repository -n <namespace> 列出)
  • <pod-name>:pod 名称(使用 kubectl get pods -n <pac-namespace> 列出)
  • <name>:PipelineRun 名称(使用 kubectl get pipelinerun -n <namespace> 列出)
  • <gitlab-secret>:GitLab token secret 名称(检查 Repository CR spec)

PAC 组件未部署

症状

OpenShiftPipelinesAsCode CR 显示 Ready: False,或者 pod 未启动。

故障排查步骤

  1. 检查 CR 状态:

    kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml

输出示例(节选):

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
status:
  conditions:
  - status: "False"
    type: Ready
    reason: DeploymentFailed
  1. 检查 CR 事件:

    kubectl describe openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

输出示例(节选):

Name:         pipelines-as-code
Status:       False
Events:
Type     Reason           Age   From              Message
----     ------           ----  ----              -------
Warning  DeploymentFailed 5m    tekton-operator   Failed to deploy PAC component
  1. 检查 TektonInstallerSet:

    kubectl get tektoninstallersets | grep openshiftpipelinesascode
    kubectl describe tektoninstallerset <name>

    注意:TektonInstallerSet 是一个 cluster-scoped 资源。这里的检查仅用于故障排查,且为只读操作。请勿直接修改或删除它。如果问题仍然存在,请通过 OpenShiftPipelinesAsCode CR 进行排查。

输出示例:

NAME                                             AGE
openshiftpipelinesascode-main-deployment-4bzwx   153d
openshiftpipelinesascode-main-static-s7qn2       153d
openshiftpipelinesascode-post-cdwjw              153d
  1. 检查 Operator 日志:

    kubectl logs -n <pac-namespace> -l app=tekton-operator --tail=100

输出示例(示例日志条目):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"operator","msg":"Failed to deploy PAC","error":"..."}

常见原因

  • CR 名称不正确:必须严格为 pipelines-as-code
  • Operator 未运行:检查 Tekton Operator 状态
  • Namespace 问题:验证 targetNamespace 是否存在
  • 资源冲突:检查是否存在已有资源

解决方案

  1. 确认 CR 名称为 pipelines-as-code
  2. 确保 Tekton Operator 正在运行
  3. 检查 namespace 是否存在(将 <pac-namespace> 替换为你的实际 PAC namespace):kubectl get namespace <pac-namespace>
  4. 如有需要,删除并重新创建 CR

PAC pod 未启动

症状

PAC pod 处于 Pending 或 CrashLoopBackOff 状态。

故障排查步骤

  1. 检查 pod 状态(将 <pac-namespace> 替换为你的 PAC namespace):

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

输出示例:

NAME                                          READY   STATUS             RESTARTS   AGE
pipelines-as-code-controller-769bf5c88c-xxxxx  0/1     CrashLoopBackOff   5          113d
pipelines-as-code-watcher-546d6cd86d-xxxxx    0/1     Pending            0          113d
  1. 检查 pod 日志:

    首先,获取 pod 名称(将 <pac-namespace> 替换为你的 PAC namespace):

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

    然后检查日志(将 <pod-name> 替换为实际的 pod 名称):

    kubectl logs -n <pac-namespace> <pod-name>

输出示例(示例错误):

Error: failed to start controller: cannot connect to database
  1. 检查 pod 事件:

    先获取 pod 名称,然后描述它(将 <pod-name> 替换为实际的 pod 名称):

    kubectl describe pod <pod-name> -n <pac-namespace>

输出示例(节选):

Name:         pipelines-as-code-controller-xxxxx
Status:       CrashLoopBackOff
Events:
Type     Reason     Age   From               Message
----     ------     ----  ----               -------
Warning  Failed     5m    kubelet            Error: ImagePullBackOff
  1. 检查资源限制:

    kubectl get pod <pod-name> -n <pac-namespace> -o yaml | grep -A 5 resources

输出示例:

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

Webhook 未接收事件

症状

GitLab webhook 事件未到达 PAC,pipeline 未触发。

故障排查步骤

  1. 检查 GitLab 中的 webhook 配置:

    • 转到 GitLab project → Settings → Webhooks
    • 验证 webhook URL 是否正确
    • 检查 webhook secret 是否与 Repository CR 匹配
  2. 检查 PAC controller 日志(将 <pac-namespace> 替换为你的 PAC namespace):

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100

输出示例(示例日志条目):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Received webhook event"}
{"level":"error","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Webhook validation failed","error":"invalid signature"}
  1. 从 GitLab 测试 webhook:

    • 转到 GitLab project → Settings → Webhooks
    • 点击 "Test" → "Push events"
    • 检查 webhook 响应
  2. 验证 controller URL 可访问:

    # If using Ingress
    curl -I http://pac.example.com

输出示例:

HTTP/1.1 200 OK
Content-Type: text/plain
# If using NodePort
curl -I http://<node-ip>:<node-port>

输出示例:

HTTP/1.1 200 OK
Content-Type: text/plain
  1. 检查 Repository CR:

    首先,列出所有 Repository CR 以查找名称(将 <namespace> 替换为你的 Pipeline namespace):

    kubectl get repository -n <namespace>

    然后检查特定的 Repository CR(将 <repo-name> 替换为实际的 repository 名称):

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

输出示例(节选):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  git_provider:
    webhook_secret:
      name: webhook-secret
      key: secret

常见原因

  • controller URL 无法访问:防火墙或网络问题
  • webhook secret 不匹配:GitLab 中的 secret 与 Repository CR 不一致
  • webhook URL 错误:配置了错误的 controller URL
  • Ingress/Service 未配置:controller 未暴露

解决方案

  1. 验证 GitLab 服务器可以访问 controller URL
  2. 确保 GitLab 和 Repository CR 中的 webhook secret 一致
  3. 检查 Ingress/Service 配置
  4. 使用 curl 手动测试 webhook

验证

应用解决方案后,请验证修复结果:

  1. 从 GitLab 测试 webhook:

    • 转到 GitLab project → Settings → Webhooks
    • 点击 "Test" → "Push events"
    • 检查 webhook 是否返回 200 OK 响应
  2. 检查 PAC controller 日志,查看 webhook 事件:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i webhook

    你应该能看到表明 webhook 事件正在被接收的日志条目。

Pipeline 未触发

症状

发生 Git 事件时,没有创建 pipeline。

故障排查步骤

  1. 检查 Pipeline 注解:

    cat .tekton/pipelinerun.yaml | grep pipelinesascode.tekton.dev

输出示例:

pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
  1. 验证分支名称是否匹配:

    git branch --show-current
    git log --oneline -1

输出示例:

main
abc1234 Test commit
  1. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i trigger

输出示例(示例日志条目):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing trigger","branch":"main","event":"push"}
{"level":"warn","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Branch mismatch","expected":"main","actual":"develop"}
  1. 检查 Repository CR 状态:

    首先,列出 Repository CR 以查找名称:

    kubectl get repository -n <namespace>

    然后检查 Repository CR(将 <repo-name> 替换为实际的 repository 名称):

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

输出示例(节选):

Name:         my-repo
Namespace:    project-pipelines
Status:       Ready
Events:
Type    Reason   Age   From     Message
----    ------   ----  ----     -------
Normal  Ready    5m    pac      Repository validated
  1. 验证 pipeline 文件是否存在:

    git ls-files .tekton/

输出示例:

.tekton/pipelinerun.yaml

常见原因

  • 注解语法错误:注解格式不正确
  • 分支名称不匹配:分支模式与实际分支不匹配
  • 未找到 pipeline 文件:文件不在预期位置
  • 路径过滤:变更的文件不符合路径过滤条件
  • 未找到 Repository CR:仓库没有匹配的 Repository CR

解决方案

  1. 验证注解语法:使用 pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" 和 pipelinesascode.tekton.dev/on-event: "[push]",而不是已弃用的 on-push 注解
  2. 确认分支名称完全匹配(区分大小写)
  3. 确保仓库中存在 .tekton/pipelinerun.yaml
  4. 如已配置,请检查路径过滤
  5. 验证 Repository CR 存在且与 repository URL 匹配

验证

应用解决方案后,请验证修复结果:

  1. 触发测试事件:

    • 向 pipeline 注解中指定的分支推送一个 commit
    • 或在测试 MR 触发时创建一个 Merge Request
  2. 检查是否创建了 PipelineRun:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -5

    你应该会在 Git 事件之后看到一个新的 PipelineRun 被创建。

  3. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i trigger

    查找表明事件已被处理的日志条目。

未创建 PipelineRuns

症状

已接收到 webhook 事件,但没有创建 PipelineRuns。

故障排查步骤

  1. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=200

输出示例(示例错误):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Failed to create PipelineRun","error":"namespaces \"project-pipelines\" not found"}
  1. 检查 Repository CR:

    首先,列出 Repository CR 以查找名称:

    kubectl get repository -n <namespace>

    然后检查 Repository CR(将 <repo-name> 替换为实际的 repository 名称):

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

输出示例(节选):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
# ......
  1. 验证 namespace 是否存在:

    kubectl get namespace <namespace>

输出示例:

NAME                STATUS   AGE
project-pipelines   Active   10m

如果 namespace 不存在,你会看到:

Error from server (NotFound): namespaces "project-pipelines" not found
  1. 检查 RBAC 权限:

    kubectl auth can-i create pipelineruns --namespace <namespace>

输出示例:

yes
  1. 检查 GitLab token:

    首先,从 Repository CR 中找到 secret 名称:

    kubectl get repository <repo-name> -n <namespace> -o jsonpath='{.spec.git_provider.secret.name}'

    然后检查 secret(将 <gitlab-secret> 替换为实际的 secret 名称):

    kubectl get secret <gitlab-secret> -n <namespace> -o yaml

输出示例(节选,token 已进行 base64 编码):

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
data:
  token: Z2xwYXQt...

常见原因

  • namespace 不存在:目标 namespace 尚未创建
  • RBAC 权限问题:PAC ServiceAccount 缺少权限
  • GitLab token 无效:token 已过期或不正确
  • pipeline 定义错误:YAML 或 Tekton 语法无效
  • 无法访问 repository:无法访问 Git repository

解决方案

  1. 如果缺少 namespace,则创建它:

    kubectl create namespace <namespace>

输出示例:

namespace/project-pipelines created
  1. 验证 RBAC:检查 ServiceAccount 和 RoleBindings

    检查 PAC 使用哪个 ServiceAccount:

    kubectl get pod -n <pac-namespace> -l app=pipelines-as-code-controller -o jsonpath='{.items[0].spec.serviceAccountName}'

    检查 ServiceAccount 是否具有所需权限:

    kubectl auth can-i create pipelineruns --namespace <namespace> --as=system:serviceaccount:<pac-namespace>:<service-account-name>
  2. 如果 GitLab token 已过期,请更新它

  3. 校验 pipeline YAML 语法

  4. 测试 GitLab token:

    curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"

输出示例(如果 token 有效):

{
  "id": 1,
  "username": "user",
  "email": "user@example.com"
}

如果 token 无效:

{"message":"401 Unauthorized"}

验证

应用解决方案后,请验证修复结果:

  1. 触发一个 Git 事件(push 或创建 MR),并检查是否创建了 PipelineRun:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -1
  2. 检查 PipelineRun 状态:

    kubectl describe pipelinerun <name> -n <namespace>

    PipelineRun 应该已创建并开始执行。

未找到 Task

症状

PipelineRun 失败,并报错 "task not found"。

故障排查步骤

  1. 检查 PipelineRun 状态:

    首先,列出 PipelineRuns 以查找名称:

    kubectl get pipelinerun -n <namespace>

    然后检查该 PipelineRun(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace> -o yaml
    kubectl describe pipelinerun <name> -n <namespace>

输出示例(节选,显示错误):

status:
  conditions:
  - status: "False"
    type: Succeeded
    reason: TaskNotFound
  taskRuns:
    task-run-name:
      status:
        conditions:
        - message: 'Task "my-task" not found'
  1. 检查 Task 引用:

    cat .tekton/pipelinerun.yaml | grep -A 5 taskRef

输出示例:

taskRef:
  name: my-task
  kind: Task
  1. 验证 Task 是否存在:

    # For local tasks
    kubectl get task <task-name> -n <namespace>

输出示例(如果 task 存在):

NAME       AGE
my-task    10m

如果 task 不存在:

Error from server (NotFound): tasks.tekton.dev "my-task" not found
# For Tekton Hub tasks
curl https://api.hub.tekton.dev/v1/resource/task/<task-name>

输出示例(如果 task 存在):

{
  "id": 1,
  "name": "git-clone",
  "kind": "Task",
  "catalog": {
    "id": 1,
    "name": "Tekton"
  }
}
  1. 检查网络连通性:

    # Test Tekton Hub access
    curl https://api.hub.tekton.dev/v1/resource/task/git-clone

输出示例(如果可访问):

{"id":1,"name":"git-clone",...}
# Test remote URL access
curl <remote-task-url>

输出示例(如果可访问):

apiVersion: tekton.dev/v1
kind: Task
...

常见原因

  • Task 名称错误:Task 名称中有拼写错误
  • Task 不在该 namespace 中:Task 定义在其他 namespace
  • Tekton Hub 不可用:访问 Tekton Hub 时出现网络问题
  • 远程 URL 不可访问:无法从远程 URL 获取 task
  • Task resolver 错误:resolver 配置不正确

解决方案

  1. 检查 task 名称拼写
  2. 确认 task 存在于正确的 namespace 中
  3. 测试 Tekton Hub 连通性
  4. 验证远程 URL 可访问
  5. 检查 task resolver 配置

变量未解析

症状

像 {{revision}} 这样的 pipeline 变量没有被替换。

故障排查步骤

  1. 检查变量语法:

    cat .tekton/pipelinerun.yaml | grep -E "\{\{|\}\}"

输出示例:

revision: {{revision}}
repo_url: {{repo_url}}
  1. 使用 Dry-Run 验证 YAML 语法:

    使用 kubectl apply --dry-run=client 验证 PipelineRun YAML 语法,并尽早捕获错误:

    kubectl apply --dry-run=client -f .tekton/pipelinerun.yaml -n <namespace>

输出示例(如果语法有效):

pipelinerun.tekton.dev/my-pipeline created (dry run)

输出示例(如果存在语法错误):

error: error validating ".tekton/pipelinerun.yaml": error validating data: [ValidationError(PipelineRun.spec): unknown field "invalid-field" in tekton.dev.v1.PipelineRun.spec, ...]

注意:此 dry-run 检查会验证 YAML 语法和 Tekton schema,但不会验证变量解析(dry-run 中像 {{revision}} 这样的变量仍会保持为字面字符串)。如需排查变量解析问题,请检查 PAC controller 日志。

  1. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i variable

输出示例(示例日志条目):

{"level":"warn","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Unknown variable","variable":"{{Revision}}"}
  1. 验证变量名称:

    • {{revision}} - 正确
    • {{Revision}} 或 {{REVISION}} - 错误(区分大小写)
    • 使用双大括号:{{variable_name}}
  2. 检查 PipelineRun 参数:

    首先,获取 PipelineRun 名称:

    kubectl get pipelinerun -n <namespace>

    然后检查参数(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.params}'

输出示例:

[
  {
    "name": "revision",
    "value": "abc1234"
  },
  {
    "name": "repo_url",
    "value": "https://gitlab.com/user/repo"
  }
]

常见原因

  • 语法错误:缺少大括号或格式不正确
  • 大小写敏感:变量名区分大小写
  • 变量不可用:当前事件类型不支持该变量(例如,{{pull_request_number}} 仅适用于 pull_request 事件)
  • PAC 版本:旧版本 PAC 可能不支持某些变量

解决方案

  1. 验证变量语法:使用 {{variable_name}} 格式,例如 {{revision}} 或 {{repo_url}}
  2. 检查变量名是否正确(区分大小写):{{repo_owner}}、{{source_branch}}、{{pull_request_number}}
  3. 确保变量对该事件类型可用:某些变量(如 {{pull_request_number}})仅适用于 pull_request 事件
  4. 如有需要,将 PAC 更新到最新版本

有关可用变量的完整列表,请参见 Parameterizing Commits and URLs。

验证

应用解决方案后,请验证修复结果:

  1. 检查已创建的 PipelineRun 中变量是否已解析:

    kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.params}' | jq .

    变量应被替换为实际值(例如,{{revision}} 应替换为 commit SHA)。

  2. 检查 PAC controller 日志,确认变量解析情况:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i variable

    应该不会出现关于未知变量的警告。

状态未上报到 GitLab

症状

Pipeline 运行成功,但状态未显示在 GitLab 中。

故障排查步骤

  1. 检查 PAC watcher 日志:

    kubectl logs -n <pac-namespace> -l app.kubernetes.io/name=watcher --tail=100

输出示例(示例日志条目):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"watcher","msg":"Failed to update status","error":"401 Unauthorized"}
  1. 检查 GitLab token:

    首先,从 Repository CR 中找到 secret 名称:

    kubectl get repository <repo-name> -n <namespace> -o jsonpath='{.spec.git_provider.secret.name}'

    然后检查 secret(将 <gitlab-secret> 替换为实际的 secret 名称):

    kubectl get secret <gitlab-secret> -n <namespace> -o yaml

输出示例(节选,token 已进行 base64 编码):

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
data:
  token: Z2xwYXQt...
  1. 测试 GitLab API 访问:

    TOKEN=$(kubectl get secret <gitlab-secret> -n <namespace> -o jsonpath='{.data.token}' | base64 -d)
    curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab.com/api/v4/user"

输出示例(如果 token 有效):

{
  "id": 1,
  "username": "user",
  "email": "user@example.com"
}

如果 token 无效或已过期:

{
  "message": "401 Unauthorized"
}
  1. 检查 Repository CR:

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

输出示例(节选):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  git_provider:
    secret:
      name: gitlab-secret
      key: token
  1. 验证 PipelineRun 状态:

    列出 PipelineRuns 以查找名称:

    kubectl get pipelinerun -n <namespace>

    然后检查状态(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace>

输出示例:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   5 minutes ago  30s        Succeeded

常见原因

  • GitLab token 无效:token 已过期或不正确
  • token 权限不足:token 缺少所需的 scope
  • 网络问题:无法访问 GitLab API
  • PAC watcher 未运行:watcher pod 未运行
  • Repository CR 配置错误:GitLab 配置不正确

解决方案

  1. 验证 GitLab token 有效且未过期
  2. 确保 token 具有 api scope
  3. 测试 GitLab API 连通性
  4. 检查 PAC watcher pod 是否在运行
  5. 验证 Repository CR 中的 GitLab 配置

验证

应用解决方案后,请验证修复结果:

  1. 检查 PAC watcher 日志,确认状态更新成功:

    kubectl logs -n <pac-namespace> -l app.kubernetes.io/name=watcher --tail=50 | grep -i status

    你应该能看到表明状态更新已成功发送的日志条目。

  2. 检查 GitLab UI:

    • 转到你的 GitLab project
    • 检查 Merge Request 或 commit
    • 验证是否显示了 pipeline 状态(例如,“passed”、“failed”、“running”)
  3. 验证 PipelineRun 已完成:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -1

    PipelineRun 应显示 Succeeded 或 Failed 状态,并且该状态应反映在 GitLab 中。

评论命令不生效

症状

像 /retest 这样的评论命令没有触发 pipeline。

故障排查步骤

  1. 检查注解配置:

    cat .tekton/pipelinerun.yaml | grep on-comment

    输出示例:

    pipelinesascode.tekton.dev/on-comment: "retest"
  2. 验证评论格式:

    • 命令必须单独占一行,或位于一行的开头
    • /retest - 正确
    • Please /retest - 错误(命令不在开头)
  3. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i comment

    输出示例(示例日志条目):

    {"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing comment command","command":"/retest"}
    {"level":"warn","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Comment command not at start of line","comment":"Please /retest"}
  4. 验证 Merge Request 是否存在:

    • 评论命令仅在 Merge Requests 中生效
    • 普通 commit 不可用
  5. 检查 webhook 配置:

    # In GitLab, verify webhook includes "Comments" trigger

常见原因

  • 缺少注解:未配置 on-comment 注解
  • 命令格式问题:命令不在行首
  • 不在 Merge Request 中:评论命令仅在 Merge Requests 中生效
  • webhook 未配置:webhook 未启用 Comments 事件
  • 命令名称不匹配:评论中的命令与注解不一致

解决方案

  1. 添加 on-comment 注解:pipelinesascode.tekton.dev/on-comment: "retest"
  2. 确保命令位于行首
  3. 仅在 Merge Requests 中使用命令
  4. 在 GitLab webhook 配置中启用 "Comments"
  5. 命令名称必须完全匹配(区分大小写)

获取帮助

如果你仍然遇到问题:

  1. 查看日志:检查所有组件日志中的错误
  2. 验证配置:再次检查所有配置文件
  3. 查看文档:查阅本指南中的 PAC 文档
  4. 回顾故障排查:查看本文档中的其他故障排查章节

下一步