常见问题

适用于所有用户

本故障排查指南涵盖 管理员（组件部署、配置）和 普通用户（仓库设置、Pipeline 执行）遇到的问题。

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

<pac-namespace>：PAC 组件（controller、watcher、webhook）部署所在的 namespace。默认值为 tekton-pipelines，但可以通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 自定义。
<namespace>：创建 PipelineRun 的 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。

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 未启动。

故障排查步骤

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

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

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

检查 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 是否存在
资源冲突：检查是否存在已有资源

解决方案

确认 CR 名称为 pipelines-as-code
确保 Tekton Operator 正在运行
检查 namespace 是否存在（将 <pac-namespace> 替换为你的实际 PAC namespace）：kubectl get namespace <pac-namespace>
如有需要，删除并重新创建 CR

PAC Pod 未启动

症状

PAC pod 处于 Pending 或 CrashLoopBackOff 状态。

故障排查步骤

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

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

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

检查资源限制：

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 未触发。

故障排查步骤

检查 GitLab 中的 Webhook 配置：
- 前往 GitLab project → Settings → Webhooks
- 验证 webhook URL 是否正确
- 检查 webhook secret 是否与 Repository CR 匹配

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

从 GitLab 测试 Webhook：
- 前往 GitLab project → Settings → Webhooks
- 点击 "Test" → "Push events"
- 检查 webhook 响应

验证 Controller URL 是否可访问：

# 如果使用 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

检查 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 未暴露

解决方案

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

验证

应用解决方案后，请验证修复是否生效：

从 GitLab 测试 webhook：
- 前往 GitLab project → Settings → Webhooks
- 点击 "Test" → "Push events"
- 检查 webhook 是否返回 200 OK 响应
检查 PAC Controller 日志，查看 webhook 事件：
kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i webhook
你应该能看到表示 webhook 事件正在被接收的日志条目。

Pipeline 未触发

症状

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

故障排查步骤

检查 Pipeline 注解：

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

示例输出：

pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"

验证分支名称是否匹配：

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

示例输出：

main
abc1234 Test commit

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

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

验证 Pipeline 文件是否存在：
git ls-files .tekton/

示例输出：

.tekton/pipelinerun.yaml

常见原因

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

解决方案

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

验证

应用解决方案后，请验证修复是否生效：

触发测试事件：
- 向 pipeline 注解中指定的分支推送 commit
- 或在测试 MR 触发器时创建 Merge Request
检查是否创建了 PipelineRun：
kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -5
你应该会看到 Git 事件触发后创建了一个新的 PipelineRun。

检查 PAC Controller 日志：

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

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

未创建 PipelineRun

症状

已接收到 webhook 事件，但没有创建 PipelineRun。

故障排查步骤

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

检查 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:
# ......

验证 Namespace 是否存在：
kubectl get namespace <namespace>

示例输出：

NAME                STATUS   AGE
project-pipelines   Active   10m

如果 namespace 不存在，你会看到：

Error from server (NotFound): namespaces "project-pipelines" not found

检查 RBAC 权限：

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

示例输出：

yes

检查 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 语法无效
仓库访问问题：无法访问 Git repository

解决方案

如果缺少 namespace，则创建它：
kubectl create namespace <namespace>

示例输出：

namespace/project-pipelines created

验证 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>

如果 GitLab token 已过期，请更新它
验证 pipeline YAML 语法

测试 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"}

验证

应用解决方案后，请验证修复是否生效：

触发 Git 事件（push 或创建 MR），检查是否创建了 PipelineRun：

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

检查 PipelineRun 状态：
kubectl describe pipelinerun <name> -n <namespace>
PipelineRun 应该已经创建并开始执行。

未找到 Task

症状

PipelineRun 因 "task not found" 错误而失败。

故障排查步骤

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

检查 Task 引用：

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

示例输出：

taskRef:
  name: my-task
  kind: Task

验证 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"
  }
}

检查网络连通性：

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

示例输出（如果可访问）：

{"id":1,"name":"git-clone",...}

# 测试远程 URL 访问
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 配置不正确

解决方案

验证 task 名称拼写
检查 task 是否存在于正确的 namespace 中
测试 Tekton Hub 连通性
验证远程 URL 可访问
检查 task resolver 配置

变量未解析

症状

类似 {{revision}} 的 pipeline 变量没有被替换。

故障排查步骤

检查变量语法：

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

示例输出：

revision: {{revision}}
repo_url: {{repo_url}}

使用 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，但不会验证变量解析（像 {{revision}} 这样的变量在 dry-run 中仍会保持字面字符串）。关于变量解析问题，请检查 PAC controller 日志。

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

验证变量名称：
- {{revision}} - 正确
- {{Revision}} 或 {{REVISION}} - 错误（区分大小写）
- 使用双大括号：{{variable_name}}
检查 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 可能不支持某些变量

解决方案

验证变量语法：使用 {{variable_name}} 格式，例如 {{revision}} 或 {{repo_url}}
检查变量名称是否正确（区分大小写）：{{repo_owner}}、{{source_branch}}、{{pull_request_number}}
确保该变量适用于对应的事件类型：某些变量（例如 {{pull_request_number}}）仅适用于 pull_request 事件
如有需要，将 PAC 更新到最新版本

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

验证

应用解决方案后，请验证修复是否生效：

检查创建的 PipelineRun 中变量是否已解析：
kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.params}' | jq .
变量应被替换为实际值（例如，{{revision}} 应替换为 commit SHA）。

检查 PAC Controller 日志，查看变量解析情况：

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

不应再有关于未知变量的警告。

未将状态上报给 GitLab

症状

pipeline 运行成功，但 GitLab 中未显示状态。

故障排查步骤

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

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

测试 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"
}

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

验证 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 配置不正确

解决方案

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

验证

应用解决方案后，请验证修复是否生效：

检查 PAC Watcher 日志，确认状态更新成功：
kubectl logs -n <pac-namespace> -l app.kubernetes.io/name=watcher --tail=50 | grep -i status
你应该能看到表示状态更新已成功发送的日志条目。
检查 GitLab UI：
- 前往你的 GitLab project
- 检查 Merge Request 或 commit
- 验证是否显示 pipeline 状态（例如 "passed"、"failed"、"running"）
验证 PipelineRun 已完成：
kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -1
PipelineRun 应显示 Succeeded 或 Failed 状态，并且该状态应反映在 GitLab 中。

评论命令不工作

症状

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

故障排查步骤

检查注解配置：

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

示例输出：

pipelinesascode.tekton.dev/on-comment: "retest"

验证评论格式：
- 命令必须单独成行，或位于某一行的开头
- /retest - 正确
- Please /retest - 错误（命令不在开头）

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

验证 Merge Request 是否存在：
- 评论命令仅适用于 Merge Request
- 不适用于普通 commit

检查 Webhook 配置：

# In GitLab, verify webhook includes "Comments" trigger

常见原因

缺少注解：未配置 on-comment 注解
命令格式：命令不在行首
不在 Merge Request 中：评论命令仅适用于 Merge Request
Webhook 未配置：webhook 中未启用 Comments 事件
命令名称不匹配：评论中的命令与注解不一致

解决方案

添加 on-comment 注解：pipelinesascode.tekton.dev/on-comment: "retest"
确保命令位于行首
仅在 Merge Request 中使用命令
在 GitLab webhook 配置中启用 "Comments"
严格匹配命令名称（区分大小写）

PAC 设置没有生效

症状

已向 OpenShiftPipelinesAsCode CR 添加某项设置并且应用成功，但 PAC 仍然表现得像该设置仍使用默认值。CR 报告 READY=True，没有记录事件或错误，重新读取 CR 后显示该 key 已从 spec.settings 中消失。

这只影响 Alauda 扩展设置：custom-console-url-namespace-vars、replace-empty-template-vars-with-empty 和 enable-pull-request-number-on-push-events。

请注意，这里的症状是“默认值生效”，而不是“功能缺失”。当 key 在其 ConfigMap 中不存在时，PAC 会回退到该设置的内置默认值，因此关闭默认开启的设置与开启默认关闭的设置受到的影响是一样的。

故障排查步骤

下面的命令使用两个占位符。请先在同一个 shell 中设置它们，这样后续命令就可以直接粘贴：

SETTING=custom-console-url-namespace-vars   # the setting you configured
PAC_NS=tekton-pipelines                     # spec.targetNamespace of the PAC CR

检查该 key 是否仍保留在 CR 中：
kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code \ -o jsonpath="{.spec.settings.$SETTING}"
这一步只有在你把 key 写在 spec.settings 下时才有意义；如果输出为空，说明 operator 已将其丢弃。如果你已经把 key 移到 spec.options.configMaps，那么这里输出为空是预期结果——请直接进入第 2 步。
检查 PAC 实际读取的 ConfigMap。这是权威检查——spec.settings 只描述意图：
kubectl get configmap pipelines-as-code -n "$PAC_NS" \ -o jsonpath="{.data.$SETTING}"
将输出与你期望的值进行比较。任何其他结果都意味着 PAC 没有使用你的配置。请注意，当你故意将 key 设置为空字符串时，空输出是正确结果，例如用于清除你不再需要的映射。

常见原因

key 写在 spec.settings 下：operator 的默认填充 webhook 会根据上游 Pipelines as Code settings 结构重新构建 spec.settings。Alauda 扩展设置在该结构中没有对应字段，因此在保存时会被丢弃——整个过程静默发生，不会报错，也不会产生事件。
key 直接写入 ConfigMap：手动编辑在普通 reconcile 中不会丢失，因为 operator 会将其渲染后的 manifest 与一个 hash 注解进行比较，而你的修改不会改变该注解。一旦渲染后的 manifest 发生变化——例如 PAC 配置变更、operator 升级，或 installer set 重新构建——它就会被静默覆盖。因此，手动编辑 ConfigMap 看起来像是生效了，但会在不可预测的时刻停止生效。

解决方案

将 key 移到 spec.options.configMaps，operator 会按 key 逐项合并到 ConfigMap 中，并且不会重写它：

spec:
  options:
    disabled: false
    configMaps:
      pipelines-as-code:
        data:
          custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

然后重复第 2 步，确认该值已进入 ConfigMap。详细说明和完整 key 列表请参阅 Where to Put Each Setting。

获取帮助

如果你仍然遇到问题：

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

下一步

管理 PAC 组件 - 部署和管理指南
指南 - Repository 设置教程
触发 PAC Pipelines - 自动事件和评论命令

#常见问题

#目录

#开始之前

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

#2. 确定你的 namespaces

#3. 获取资源名称

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

#PAC 组件未部署

#症状

#故障排查步骤

#常见原因

#解决方案

#PAC Pod 未启动

#症状

#故障排查步骤

#Webhook 未接收事件

#症状

#故障排查步骤

#常见原因

#解决方案

#验证

#Pipeline 未触发

#症状

#故障排查步骤

#常见原因

#解决方案

#验证

#未创建 PipelineRun

#症状

#故障排查步骤

#常见原因

#解决方案

#验证

#未找到 Task

#症状

#故障排查步骤

#常见原因

#解决方案

#变量未解析

#症状

#故障排查步骤

#常见原因

#解决方案

#验证

#未将状态上报给 GitLab

#症状

#故障排查步骤

#常见原因

#解决方案

#验证

#评论命令不工作

#症状

#故障排查步骤

#常见原因

#解决方案

#PAC 设置没有生效

#症状

#故障排查步骤

#常见原因

#解决方案

#获取帮助

#下一步

常见问题

目录

开始之前

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

2. 确定你的 namespaces

3. 获取资源名称

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

PAC 组件未部署

症状

故障排查步骤

常见原因

解决方案

PAC Pod 未启动

症状

故障排查步骤

Webhook 未接收事件

症状

故障排查步骤

常见原因

解决方案

验证

Pipeline 未触发

症状

故障排查步骤

常见原因

解决方案

验证

未创建 PipelineRun

症状

故障排查步骤

常见原因

解决方案

验证

未找到 Task

症状

故障排查步骤

常见原因

解决方案

变量未解析

症状

故障排查步骤

常见原因

解决方案

验证

未将状态上报给 GitLab

症状

故障排查步骤

常见原因

解决方案

验证

评论命令不工作

症状

故障排查步骤

常见原因

解决方案

PAC 设置没有生效

症状

故障排查步骤

常见原因

解决方案

获取帮助

下一步