常见问题
本故障排查指南涵盖 管理员(组件部署、配置)和 普通用户(仓库设置、流水线执行)可能遇到的问题。
重要:在本文档中,我们使用两个不同的命名空间:
<pac-namespace>:PAC 组件(controller、watcher、webhook)部署所在的命名空间。默认值为tekton-pipelines,但可以通过OpenShiftPipelinesAsCodeCR 中的targetNamespace进行自定义。<namespace>:创建 PipelineRuns 的命名空间。在创建 Repository CR 时指定,可以是集群中的任意命名空间。
请将这些占位符替换为你实际的命名空间名称。
本文档提供了使用 Pipelines-as-Code(PAC)时遇到的常见问题的故障排查步骤。
目录
开始之前1. 检查 PAC 组件是否正在运行2. 确定你的命名空间3. 获取资源名称4. 本文档中使用的常见占位符PAC 组件未部署现象故障排查步骤常见原因解决方案PAC pod 未启动现象故障排查步骤自动 Webhook 注册失败现象故障排查步骤自动 Webhook 注册失败的常见原因说明Webhook 未接收事件现象故障排查步骤常见原因解决方案验证Pipeline 未触发现象故障排查步骤常见原因解决方案验证未创建 PipelineRuns现象故障排查步骤常见原因解决方案验证未找到任务现象故障排查步骤常见原因解决方案变量未解析现象故障排查步骤常见原因解决方案验证状态未报告到 GitLab现象故障排查步骤常见原因解决方案验证评论命令不生效现象故障排查步骤常见原因解决方案获取帮助后续步骤开始之前
在排查具体问题之前,请先验证以下基本项:
1. 检查 PAC 组件是否正在运行
确认所有 PAC pod 都处于运行状态(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
示例输出(所有 pod 都应为 Running):
2. 确定你的命名空间
获取 PAC 命名空间(PAC 组件部署所在位置):
如果命令失败或返回为空,请使用默认值:tekton-pipelines
获取 Pipeline 命名空间(创建 PipelineRuns 的位置):
这会显示所有 Repository CR 及其命名空间。命名空间列显示 PipelineRuns 将在哪里创建。
3. 获取资源名称
获取 pod 名称:
获取 Repository CR 名称:
获取 PipelineRun 名称:
4. 本文档中使用的常见占位符
<pac-namespace>:PAC 部署命名空间(默认值:tekton-pipelines)<namespace>:PipelineRun 命名空间(因仓库而异)<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 状态:
示例输出(已截断):
-
检查 CR 事件:
示例输出(已截断):
-
检查 TektonInstallerSet:
注意:
TektonInstallerSet是集群作用域资源。此处仅进行只读检查以便排查问题。请勿直接修改或删除它。如果问题仍然存在,请通过OpenShiftPipelinesAsCodeCR 进行排查。
示例输出:
-
检查 Operator 日志:
示例输出(示例日志条目):
常见原因
- CR 名称不正确:必须严格为
pipelines-as-code - Operator 未运行:检查 Tekton Operator 状态
- 命名空间问题:确认
targetNamespace存在 - 资源冲突:检查是否存在已有资源
解决方案
- 确认 CR 名称为
pipelines-as-code - 确保 Tekton Operator 正在运行
- 检查命名空间是否存在(将
<pac-namespace>替换为你的实际 PAC 命名空间):kubectl get namespace <pac-namespace> - 如有需要,删除并重新创建 CR
PAC pod 未启动
现象
PAC pod 处于 Pending 或 CrashLoopBackOff 状态。
故障排查步骤
-
检查 Pod 状态(将
<pac-namespace>替换为你的 PAC 命名空间):
示例输出:
-
检查 Pod 日志:
首先,获取 pod 名称(将
<pac-namespace>替换为你的 PAC 命名空间):然后检查日志(将
<pod-name>替换为实际 pod 名称):
示例输出(示例错误):
-
检查 Pod 事件:
先获取 pod 名称,然后描述该 pod(将
<pod-name>替换为实际 pod 名称):
示例输出(已截断):
-
检查资源限制:
示例输出:
自动 Webhook 注册失败
现象
在应用 Repository 后未创建 GitLab/GitHub webhook,或者 Repository 具有:
故障排查步骤
-
检查 Repository 注解和事件:
-
检查 webhook 注册 controller 日志:
-
验证 PAC webhook URL 来源:
如果为空,请配置 PAC 公共 URL,并将其记录到
pipelines-as-code-info.data.controller-url中。请参见 获取 PAC Webhook URL。 -
验证 token 和 webhook Secret 引用:
-
在使用共享 webhook 管理 token 时检查集中式 credential Secret 标签:
自动 Webhook 注册失败的常见原因
说明
- 先尝试 Repository 本地 token。如果返回
401或403,controller 会使用匹配的集中式 Secret 重新尝试。 - 集中式 credential Secrets 从 webhook 注册 controller 命名空间读取;controller 不会在每个 Repository 命名空间中搜索集中式凭证。
- 直接的 Repository Secrets 不需要标签。controller 只监视有效 Repository spec 所引用的 Secret 命名空间/名称对,并在这些 Secrets 变化时协调相关 Repositories。
- 请将 Repository 本地 token 的作用域限制为正常 PAC 访问。启用自动 webhook 注册时,将 webhook 管理权限存储在集中式 credential 中。
- PAC 全局 Repository 的
git_provider设置仅适用于具有本地spec.git_providerblock 的 Repositories。仅有spec.url的 Repository 会被自动 webhook 注册跳过。 - 注解
pac.tekton.alauda.io/webhook-managed-ref存储 provider hook ID。当 PAC webhook URL 变更但 provider 和仓库身份保持不变时,controller 会按 ID 更新已记录的 hook,而不是创建重复项。 - 更新
spec.url会为新仓库注册 webhook,但不会删除旧仓库上的 webhook。如果不再需要,请手动删除旧的 provider webhook。 - 删除 Repository 时会尽力清理已记录的 managed webhook。清理失败会被记录到日志并产生事件,但不会阻止移除 Repository finalizer。如果凭证已被移除或 provider API 不可达,请手动检查 provider 侧的 webhook。
- 全局禁用自动注册,或为 Repository 添加
pac.tekton.alauda.io/webhook-registration-disabled: "true",会在 controller 将 Repository 标记为 inactive 之前移除已记录的 managed webhooks。如果由于缺少凭证或 provider 访问不可用导致清理失败,controller 会保留 managed 注解和 finalizer,并在凭证或 provider 访问恢复后重试。 - 为 Repository 添加标签
pac.tekton.alauda.io/webhook-registration-disabled: "true",可跳过该 Repository 的自动 webhook 注册。
Webhook 未接收事件
现象
GitLab webhook 事件未到达 PAC,流水线未触发。
故障排查步骤
-
检查 GitLab 中的 Webhook 配置:
- 进入 GitLab 项目 → Settings → Webhooks
- 验证 webhook URL 是否正确
- 检查 webhook secret 是否与 Repository CR 匹配
-
检查 PAC Controller 日志(将
<pac-namespace>替换为你的 PAC 命名空间):
示例输出(示例日志条目):
-
从 GitLab 测试 Webhook:
- 进入 GitLab 项目 → Settings → Webhooks
- 点击 “Test” → “Push events”
- 检查 webhook 响应
-
验证 controller URL 可访问:
示例输出:
示例输出:
-
检查 Repository CR:
先列出所有 Repository CR 以找到名称(将
<namespace>替换为你的 Pipeline 命名空间):然后检查特定的 Repository CR(将
<repo-name>替换为实际仓库名称):
示例输出(已截断):
常见原因
- 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 项目 → Settings → Webhooks
- 点击 “Test” → “Push events”
- 检查 webhook 是否返回
200 OK响应
-
检查 PAC Controller 日志,确认 webhook 事件:
你应该能看到表示正在接收 webhook 事件的日志条目。
Pipeline 未触发
现象
发生 Git 事件时没有创建流水线。
故障排查步骤
-
检查 Pipeline 注解:
示例输出:
-
验证分支名称是否匹配:
示例输出:
-
检查 PAC Controller 日志:
示例输出(示例日志条目):
-
检查 Repository CR 状态:
先列出 Repository CR 以找到名称:
然后检查 Repository CR(将
<repo-name>替换为实际仓库名称):
示例输出(已截断):
-
验证 Pipeline 文件存在:
示例输出:
常见原因
- 注解语法错误:注解格式不正确
- 分支名不匹配:分支模式与实际分支不匹配
- 未找到 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 是否存在并与仓库 URL 匹配
验证
应用解决方案后,请验证修复结果:
-
触发测试事件:
- 向 pipeline 注解中指定的分支推送 commit
- 或在测试 MR 触发时创建 Merge Request
-
检查是否创建了 PipelineRun:
在 Git 事件发生后,你应该能看到创建了新的 PipelineRun。
-
检查 PAC Controller 日志:
查找表示事件已被处理的日志条目。
未创建 PipelineRuns
现象
已接收到 webhook 事件,但没有创建 PipelineRuns。
故障排查步骤
-
检查 PAC Controller 日志:
示例输出(示例错误):
-
检查 Repository CR:
先列出 Repository CR 以找到名称:
然后检查 Repository CR(将
<repo-name>替换为实际仓库名称):
示例输出(已截断):
-
验证命名空间是否存在:
示例输出:
如果命名空间不存在,你将看到:
-
检查 RBAC 权限:
示例输出:
-
检查 GitLab token:
首先,从 Repository CR 中找到 secret 名称:
然后检查该 secret(将
<gitlab-secret>替换为实际 secret 名称):
示例输出(已截断,token 经过 base64 编码):
常见原因
- 命名空间不存在:目标命名空间未创建
- RBAC 权限不足:PAC ServiceAccount 缺少权限
- GitLab token 无效:token 过期或不正确
- Pipeline 定义错误:YAML 或 Tekton 语法无效
- 仓库访问问题:无法访问 Git 仓库
解决方案
-
如果命名空间缺失,请创建:
示例输出:
-
验证 RBAC:检查 ServiceAccount 和 RoleBindings
检查 PAC 使用的 ServiceAccount:
检查该 ServiceAccount 是否具有所需权限:
-
如果 GitLab token 过期,请更新 token
-
验证 pipeline YAML 语法
-
测试 GitLab token:
示例输出(如果 token 有效):
如果 token 无效:
验证
应用解决方案后,请验证修复结果:
-
触发一个 Git 事件(push 或创建 MR),并检查是否创建了 PipelineRun:
-
检查 PipelineRun 状态:
PipelineRun 应该已创建并开始执行。
未找到任务
现象
PipelineRun 失败,并报出 “task not found” 错误。
故障排查步骤
-
检查 PipelineRun 状态:
先列出 PipelineRuns 以找到名称:
然后检查该 PipelineRun(将
<name>替换为实际 PipelineRun 名称):
示例输出(已截断,显示错误):
-
检查 Task 引用:
示例输出:
-
验证 Task 是否存在:
示例输出(如果 task 存在):
如果 task 不存在:
示例输出(如果 task 存在):
-
检查网络连通性:
示例输出(如果可访问):
示例输出(如果可访问):
常见原因
- Task 名称错误:Task 名称存在拼写错误
- Task 不在该命名空间中:Task 定义在其他命名空间
- Tekton Hub 不可用:访问 Tekton Hub 时存在网络问题
- 远程 URL 不可访问:无法从远程 URL 获取 task
- Task resolver 错误:resolver 配置不正确
解决方案
- 检查 task 名称拼写
- 检查 task 是否存在于正确的命名空间中
- 测试 Tekton Hub 连通性
- 验证远程 URL 可访问
- 检查 task resolver 配置
变量未解析
现象
像 {{revision}} 这样的流水线变量没有被替换。
故障排查步骤
-
检查变量语法:
示例输出:
-
使用 Dry-Run 验证 YAML 语法:
使用
kubectl apply --dry-run=client来验证 PipelineRun YAML 语法并尽早捕获错误:
示例输出(如果语法有效):
示例输出(如果存在语法错误):
注意:此 dry-run 检查会验证 YAML 语法和 Tekton schema,但不会验证变量解析(像 {{revision}} 这样的变量在 dry-run 中仍会保留为字面字符串)。关于变量解析问题,请检查 PAC controller 日志。
-
检查 PAC Controller 日志:
示例输出(示例日志条目):
-
验证变量名称:
{{revision}}- 正确{{Revision}}或{{REVISION}}- 错误(区分大小写)- 使用双大括号:
{{variable_name}}
-
检查 PipelineRun 参数:
首先,获取 PipelineRun 名称:
然后检查参数(将
<name>替换为实际 PipelineRun 名称):
示例输出:
常见原因
- 语法错误:缺少大括号或格式不正确
- 大小写敏感:变量名区分大小写
- 变量不可用:当前事件类型不可用该变量(例如,
{{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 更新到最新版本
有关可用变量的完整列表,请参见 参数化 Commits 和 URL。
验证
应用解决方案后,请验证修复结果:
-
检查创建的 PipelineRun 中变量是否已解析:
变量应被实际值替换(例如,
{{revision}}应替换为 commit SHA)。 -
检查 PAC Controller 日志,确认变量解析:
不应再出现有关未知变量的警告。
状态未报告到 GitLab
现象
流水线运行成功,但状态未显示在 GitLab 中。
故障排查步骤
-
检查 PAC Watcher 日志:
示例输出(示例日志条目):
-
检查 GitLab token:
首先,从 Repository CR 中找到 secret 名称:
然后检查该 secret(将
<gitlab-secret>替换为实际 secret 名称):
示例输出(已截断,token 经过 base64 编码):
-
测试 GitLab API 访问:
示例输出(如果 token 有效):
如果 token 无效或已过期:
-
检查 Repository CR:
示例输出(已截断):
-
验证 PipelineRun 状态:
列出 PipelineRuns 以找到名称:
然后检查状态(将
<name>替换为实际 PipelineRun 名称):
示例输出:
常见原因
- GitLab token 无效:token 过期或不正确
- token 权限不足:token 缺少所需 scope
- 网络问题:无法访问 GitLab API
- PAC Watcher 未运行:watcher pod 未运行
- Repository CR 配置错误:GitLab 配置不正确
解决方案
- 验证 GitLab token 有效且未过期
- 确保 token 具有
apiscope - 测试 GitLab API 连通性
- 检查 PAC Watcher pod 是否正在运行
- 验证 Repository CR 的 GitLab 配置
验证
应用解决方案后,请验证修复结果:
-
检查 PAC Watcher 日志,确认状态更新成功:
你应该能看到表示状态更新已成功发送的日志条目。
-
检查 GitLab UI:
- 进入你的 GitLab 项目
- 检查 Merge Request 或 commit
- 确认显示了流水线状态(例如,“passed”、“failed”、“running”)
-
验证 PipelineRun 已完成:
PipelineRun 应显示
Succeeded或Failed状态,并且该状态应反映到 GitLab 中。
评论命令不生效
现象
像 /retest 这样的评论命令没有触发流水线。
故障排查步骤
-
检查注解配置:
示例输出:
-
验证评论格式:
- 命令必须单独占一行,或位于某行的开头
/retest- 正确Please /retest- 错误(命令不在开头)
-
检查 PAC Controller 日志:
示例输出(示例日志条目):
-
验证 Merge Request 是否存在:
- 评论命令仅适用于 Merge Requests
- 不适用于普通 commit
-
检查 Webhook 配置:
常见原因
- 缺少注解:未配置
on-comment注解 - 命令格式问题:命令不在行首
- 不在 Merge Request 中:评论命令仅适用于 Merge Requests
- Webhook 未配置:webhook 中未启用 Comments 事件
- 命令名称不匹配:评论中的命令与注解不一致
解决方案
- 添加
on-comment注解:pipelinesascode.tekton.dev/on-comment: "retest" - 确保命令位于一行的开头
- 仅在 Merge Requests 中使用命令
- 在 GitLab webhook 配置中启用 “Comments”
- 严格匹配命令名称(区分大小写)
获取帮助
如果你仍然遇到问题:
- 查看日志:检查所有组件日志中的错误
- 验证配置:再次检查所有配置文件
- 查看文档:阅读本指南中的 PAC 文档
- 回顾故障排查:检查本文档中的其他故障排查章节
后续步骤
- 管理 PAC 组件 - 部署和管理指南
- 指南 - Repository 设置步骤
- 触发 PAC 流水线 - 自动事件和评论命令