常见问题
本故障排除指南涵盖 管理员(组件部署、配置)和 普通用户(仓库设置、流水线执行)遇到的问题。
重要:本文档中使用了两个不同的命名空间:
<pac-namespace>:部署 PAC 组件(controller、watcher、webhook)的命名空间。默认为tekton-pipelines,但可以通过targetNamespace在TektonConfigCR 中自定义。<namespace>:创建 PipelineRuns 的命名空间。创建 Repository CR 时指定此命名空间,并且可以是集群中的任意命名空间。
请将这些占位符替换为实际的命名空间名称。
本文档提供了使用 Pipelines-as-Code (PAC) 时常见问题的故障排除步骤。
目录
开始之前1. 检查 PAC 组件是否正在运行2. 确定命名空间3. 获取资源名称4. 本文档中使用的常见占位符PAC 组件未部署症状故障排查步骤常见原因解决方案PAC Pod 未启动症状故障排查步骤自动注册 Webhook 失败症状故障排查步骤常见原因注意事项Webhook 未接收事件症状故障排除步骤常见原因解决方案验证Pipeline 未触发症状故障排查步骤常见原因解决方案验证未创建 PipelineRun症状故障排查步骤常见原因解决方案验证找不到 Task症状故障排查步骤常见原因解决方案变量无法解析症状故障排查步骤常见原因解决方案验证向 GitLab 报告状态失败症状故障排查步骤常见原因解决方案验证注释命令不起作用症状排查步骤常见原因解决方案PAC 设置不起作用症状排查步骤常见原因解决方案获取帮助后续步骤开始之前
在排查具体问题之前,请先验证以下基础信息:
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 令牌 Secret 名称(检查 Repository CR spec)
PAC 组件未部署
症状
OpenShiftPipelinesAsCode CR 显示为 Ready: False,Pod 未启动,或者该 CR 根本不存在。
故障排查步骤
-
检查
TektonConfig是否请求 PAC。operator 根据TektonConfig派生OpenShiftPipelinesAsCodeCR,且仅当 profile 为all并且已启用 PAC 时才会执行。如果 CR 完全缺失,请从这里开始:预期输出:
profile 为
basic或lite,表示 operator 根本不会进入 PAC 逻辑——既不会创建 CR,也不会删除 CR。enable为空表示spec.platforms.kubernetes.pipelinesAsCode完全不存在。默认值 webhook 会使用enable: true填充该区块,但仅当某些操作写入TektonConfig时才会执行,因此在 operator 升级后尚未写入TektonConfig的集群上,该区块会保持缺失。在profile: all上——这是唯一会进入 PAC 逻辑的 profile——reconciler 会将该缺失区块视为已禁用 PAC,并删除派生的 CR。如部署 PAC 组件中所示显式写入该区块,既能立即解决问题,也能让意图在 CR 中清晰可见。 -
检查 CR 状态:
示例输出(已省略部分内容):
-
检查 CR 事件:
示例输出(已省略部分内容):
-
检查 TektonInstallerSet:
注意:
TektonInstallerSet是集群范围的资源。这是用于故障排查的只读检查。请勿直接修改或删除它。如果问题仍然存在,请通过TektonConfig和派生的OpenShiftPipelinesAsCodeCR 进行排查。
示例输出:
-
检查 operator 日志:
示例输出(示例日志条目):
常见原因
TektonConfig中未请求 PAC:profile 不是all,或者 profile 是all,但spec.platforms.kubernetes.pipelinesAsCode缺失或为enable: false。这是 CR 缺失而不是未就绪的通常原因。这两种情况有所不同:在basic或lite上,operator 不会创建 CR,也不会触碰已存在的 CR;而在all上,缺失区块或enable: false会导致 operator 删除 CR。就地升级后很容易遇到区块缺失的情况,因为只有在某些操作写入TektonConfig时才会填充该区块- operator 未运行:检查 Tekton Operator 状态
- 命名空间问题:确认
targetNamespace存在 - 资源冲突:检查是否存在同名资源
解决方案
- 在
TektonConfig中设置spec.profile: all和spec.platforms.kubernetes.pipelinesAsCode.enable: true - 确保 Tekton Operator 正在运行
- 检查命名空间是否存在(将
<pac-namespace>替换为实际的 PAC 命名空间):kubectl get namespace <pac-namespace> - 如果派生的 CR 是卡住而不是缺失,请将其删除——在
profile: all上,只要TektonConfig中仍启用了 PAC,operator 就会在下一次 reconcile 时重新创建该 CR。请勿在basic或lite上执行此操作:在那里没有任何机制会重新创建 CR,因此删除它会永久移除 PAC
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 注册控制器日志:
-
验证 PAC Webhook URL 来源:
如果为空,请配置 PAC 公共 URL,并将其记录在
pipelines-as-code-info.data.controller-url中。请参阅获取 PAC Webhook URL。 -
验证令牌和 Webhook Secret 引用:
-
使用共享 Webhook 管理令牌时,检查集中式凭证 Secret 标签:
常见原因
TLS 错误取决于发起连接的组件:
x509、certificate signed by unknown authority,或tektoncd-enhancement-controller日志中出现的类似错误,表示控制器不信任 Git provider API 证书。挂载 CA bundle 并设置SSL_CERT_FILE/GIT_SSL_CAINFO;请参阅配置自定义证书。- 如果 GitLab/GitHub Webhook 传送测试因无法验证 PAC 端点证书而失败,这是 provider 到 PAC 的问题。检查通过 TektonConfig 配置增强功能中的
pac-webhook-registration.webhook-target-tls-verify,或者安装 Git provider 信任的 CA。 - 获取 Repository 内容或报告状态时出现的
pipelines-as-code-controller错误,是独立的 PAC controller 到 provider 的信任问题,需要按照配置自定义证书配置 PAC controller CA。
注意事项
- 首先尝试 Repository 本地令牌。如果返回
401或403,控制器会使用匹配的集中式 Secret 重试。 - 集中式凭证 Secret 从 Webhook 注册控制器命名空间读取;控制器不会在每个 Repository 命名空间中搜索集中式凭证。
- 直接使用的 Repository Secret 不需要标签。控制器仅监视有效 Repository spec 所引用的 Secret 命名空间/名称对,并在这些 Secret 发生变化时 reconcile 相关 Repository。
- 将 Repository 本地令牌限制在 PAC 的正常访问范围内。启用自动 Webhook 注册后,将 Webhook 管理权限存储在集中式凭证中。
- PAC 全局 Repository
git_provider设置仅适用于具有本地spec.git_provider区块的 Repository。仅包含spec.url的 Repository 会被自动 Webhook 注册跳过。 - 注解
pac.tekton.alauda.io/webhook-managed-ref存储 provider hook ID。当 PAC Webhook URL 发生变化但 provider 和 Repository 标识保持不变时,控制器会按 ID 更新记录的 hook,而不是创建重复的 hook。 - 更新
spec.url会为新 Repository 注册 Webhook,但不会删除旧 Repository 中的 Webhook。如果不再需要,请手动删除旧 provider Webhook。 - 删除 Repository 时会尽力清理记录的受管 Webhook。清理失败会记录日志并作为事件发出,但不会阻止移除 Repository finalizer。如果凭证已被删除或 provider API 无法访问,请手动检查 provider 侧的 Webhook。
- 全局禁用自动注册,或向 Repository 添加
pac.tekton.alauda.io/webhook-registration-disabled: "true",会在控制器将 Repository 标记为非活动状态之前移除记录的受管 Webhook。如果因凭证缺失或 provider 访问不可用而导致清理失败,控制器会保留受管注解和 finalizer,并在凭证或 provider 访问恢复后重试。 - 向 Repository 添加标签
pac.tekton.alauda.io/webhook-registration-disabled: "true",可跳过该 Repository 的自动 Webhook 注册。
对于控制器日志,请使用:
Webhook 未接收事件
症状
GitLab Webhook 事件未到达 PAC,Pipeline 未触发。
故障排除步骤
-
检查 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>替换为实际的 Repository 名称):
示例输出(已缩略):
常见原因
- Controller URL 不可访问:防火墙或网络问题
- Webhook Secret 不匹配:GitLab 中的 Secret 与 Repository CR 中的不匹配
- Webhook URL 不正确:配置了错误的 controller URL
- Gateway/Ingress/Service 未配置:Controller 未暴露
解决方案
- 验证 GitLab 服务器是否可以访问 controller URL
- 确保 GitLab 和 Repository CR 中的 Webhook Secret 一致
- 检查 Gateway/Ingress/Service 配置
- 使用
curl手动测试 Webhook
验证
应用解决方案后,验证修复结果:
-
从 GitLab 测试 Webhook:
- 转到 GitLab 项目 → Settings → Webhooks
- 单击“Test” → “Push events”
- 检查 Webhook 是否返回
200 OK响应
-
检查 PAC controller 日志中的 Webhook 事件:
您应该会看到表明 Webhook 事件已接收的日志条目。
Pipeline 未触发
症状
发生 Git 事件时未创建 Pipeline。
故障排查步骤
-
检查 Pipeline 注解:
示例输出:
-
验证分支名称是否匹配:
示例输出:
-
检查 PAC controller 日志:
示例输出(日志条目示例):
-
检查 Repository CR 状态:
首先列出 Repository CR,以查找名称:
然后检查 Repository CR(将
<repo-name>替换为实际的 repository 名称):
示例输出(已省略部分内容):
-
验证 Pipeline 文件是否存在:
示例输出:
常见原因
- 注解语法错误:注解格式不正确
- 分支名称不匹配:分支模式与实际分支不匹配
- 找不到 Pipeline 文件:文件不在预期位置
- 路径过滤:已更改的文件与路径过滤器不匹配
- 找不到 Repository CR:没有与该 repository 匹配的 Repository CR
解决方案
- 验证注解语法:使用
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"和pipelinesascode.tekton.dev/on-event: "[push]",而不是已弃用的on-push注解 - 检查分支名称是否完全匹配(区分大小写)
- 确保 repository 中存在
.tekton/pipelinerun.yaml - 如果配置了路径过滤,请检查路径过滤设置
- 验证 Repository CR 是否存在,并且是否与 repository URL 匹配
验证
应用解决方案后,验证修复结果:
-
触发测试事件:
- 向 Pipeline 注解中指定的分支推送提交
- 或者在测试 MR 触发器时创建 Merge Request
-
检查是否创建了 PipelineRun:
Git 事件发生后,您应该会看到新创建的 PipelineRun。
-
检查 PAC controller 日志:
查找表明事件已处理的日志条目。
未创建 PipelineRun
症状
已接收到 Webhook 事件,但未创建 PipelineRun。
故障排查步骤
-
检查 PAC Controller 日志:
示例输出(示例错误):
-
检查 Repository CR:
首先,列出 Repository CR 以查找名称:
然后检查 Repository CR(将
<repo-name>替换为实际的 repository 名称):
示例输出(已省略部分内容):
-
验证命名空间是否存在:
示例输出:
如果命名空间不存在,您将看到:
-
检查 RBAC 权限:
示例输出:
-
检查 GitLab 令牌:
首先,从 Repository CR 中查找 secret 名称:
然后检查 secret(将
<gitlab-secret>替换为实际的 secret 名称):
示例输出(已省略部分内容,令牌经过 base64 编码):
常见原因
- 命名空间不存在:未创建目标命名空间
- RBAC 权限:PAC ServiceAccount 缺少权限
- GitLab 令牌无效:令牌已过期或不正确
- Pipeline 定义错误:YAML 或 Tekton 语法无效
- Repository 访问:无法访问 Git repository
解决方案
-
如果命名空间缺失,则创建命名空间:
示例输出:
-
验证 RBAC:检查 ServiceAccount 和 RoleBindings
检查 PAC 使用的 ServiceAccount:
检查 ServiceAccount 是否具有所需权限:
-
如果 GitLab 令牌已过期,则更新令牌
-
验证 Pipeline YAML 语法
-
测试 GitLab 令牌:
示例输出(令牌有效时):
如果令牌无效:
验证
应用解决方案后,验证修复结果:
-
触发 Git 事件(推送或创建 MR),并检查是否创建了 PipelineRun:
-
检查 PipelineRun 状态:
此时应已创建 PipelineRun 并开始执行。
找不到 Task
症状
PipelineRun 失败,并显示“找不到 task”错误。
故障排查步骤
-
检查 PipelineRun 状态:
首先,列出 PipelineRun 以查找其名称:
然后检查该 PipelineRun(将
<name>替换为实际的 PipelineRun 名称):
示例输出(已缩略,显示错误):
-
检查 Task 引用:
示例输出:
-
验证 Task 是否存在:
示例输出(Task 存在时):
Task 不存在时:
示例输出(Task 存在时):
-
检查网络连接:
示例输出(可访问时):
示例输出(可访问时):
常见原因
- Task 名称不正确:Task 名称中存在拼写错误
- Task 不在该命名空间中:Task 定义在其他命名空间中
- DevOps Hub 不可用:访问
artifacthub-shim时存在网络问题 - 远程 URL 无法访问:无法从远程 URL 获取 Task
- Task resolver 错误:resolver 配置不正确
解决方案
- 验证 Task 名称的拼写
- 检查正确的命名空间中是否存在该 Task
- 测试与
artifacthub-shim的连接 - 验证远程 URL 是否可访问
- 检查 Task resolver 配置
变量无法解析
症状
Pipeline 变量(如 {{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 更新到最新版本
有关可用变量的完整列表,请参阅参数化提交和 URL。
验证
应用解决方案后,验证修复结果:
-
检查已创建的 PipelineRun 中的变量是否已解析:
变量应已替换为实际值(例如,
{{revision}}应替换为 commit SHA)。 -
检查 PAC controller 日志中的变量解析情况:
不应存在关于未知变量的警告。
向 GitLab 报告状态失败
症状
Pipeline 成功运行,但状态未显示在 GitLab 中。
故障排查步骤
-
检查 PAC Watcher 日志:
示例输出(示例日志条目):
-
检查 GitLab 令牌:
首先,从 Repository CR 中查找 secret 名称:
然后检查 secret(将
<gitlab-secret>替换为实际的 secret 名称):
示例输出(已截断,令牌采用 base64 编码):
-
测试 GitLab API 访问:
示例输出(令牌有效时):
如果令牌无效或已过期:
-
检查 Repository CR:
示例输出(已截断):
-
验证 PipelineRun 状态:
列出 PipelineRun 以查找其名称:
然后检查状态(将
<name>替换为实际的 PipelineRun 名称):
示例输出:
常见原因
- GitLab 令牌无效:令牌已过期或不正确
- 令牌权限:令牌缺少所需的作用域
- 网络问题:无法访问 GitLab API
- PAC Watcher 未运行:Watcher Pod 未运行
- Repository CR 配置错误:GitLab 配置不正确
解决方案
- 验证 GitLab 令牌有效且未过期
- 确保令牌具有
api作用域 - 测试 GitLab API 连通性
- 检查 PAC Watcher Pod 是否正在运行
- 验证 Repository CR 中的 GitLab 配置
验证
应用解决方案后,验证修复结果:
-
检查 PAC Watcher 日志,确认状态更新成功:
应看到表明状态更新已成功发送的日志条目。
-
检查 GitLab UI:
- 转到 GitLab 项目
- 检查 Merge Request 或 commit
- 验证是否显示 Pipeline 状态(例如,“passed”、“failed”、“running”)
-
验证 PipelineRun 已完成:
PipelineRun 应显示
Succeeded或Failed状态,并且该状态应反映在 GitLab 中。
注释命令不起作用
症状
/retest 等注释命令不会触发 Pipeline。
排查步骤
-
检查注解配置:
示例输出:
-
验证注释格式:
- 命令必须单独占一行或位于行首
/retest- 正确Please /retest- 不正确(命令不在行首)
-
检查 PAC Controller 日志:
示例输出(示例日志条目):
-
验证 Merge Request 是否存在:
- 注释命令仅在 Merge Request 中有效
- 普通 commit 不支持
-
检查 Webhook 配置:
常见原因
- 缺少注解:未配置
on-comment注解 - 命令格式错误:命令不在行首
- 不在 Merge Request 中:注释命令仅在 Merge Request 中有效
- 未配置 Webhook:Webhook 中未启用 Comments 事件
- 命令名称不匹配:注释中的命令与注解不匹配
解决方案
- 添加
on-comment注解:pipelinesascode.tekton.dev/on-comment: "retest" - 确保命令位于行首
- 仅在 Merge Request 中使用命令
- 在 GitLab Webhook 配置中启用“Comments”
- 确保命令名称完全匹配(区分大小写)
PAC 设置不起作用
症状
已将设置添加到 TektonConfig.spec.platforms.kubernetes.pipelinesAsCode.settings 并成功应用,但 PAC 仍然表现得像该设置保持默认值一样。TektonConfig 和派生的 OpenShiftPipelinesAsCode CR 均报告 ready,未记录任何事件或错误,而读取 TektonConfig 时发现该键已从 settings 中消失。
这只影响 Alauda 扩展设置:custom-console-url-namespace-vars、replace-empty-template-vars-with-empty 和 enable-pull-request-number-on-push-events。
请注意,这里的症状是“默认值生效”,而不是“功能缺失”。当该键不在其 ConfigMap 中时,PAC 会回退到该设置的内置默认值,因此,关闭默认启用的设置和启用默认关闭的设置同样会受到影响。
排查步骤
以下命令使用两个占位符。请先在同一 shell 中设置它们,这样其余内容就可以直接粘贴执行:
-
检查该键是否保留在
TektonConfig中:只有当你将该键写入
settings时,此步骤才有意义;此时空输出表示 operator 丢弃了该键。如果你已将该键移至options.configMaps,则此处为空是预期结果,请直接执行第 3 步。 -
检查派生 CR。在
profile: all上,由于 PAC 正在运行,这正是此症状所表明的情况,operator 会将settings从TektonConfig复制到其中,因此该键在此处也会消失——此步骤只能确认副本保持同步,并非权威检查: -
检查 PAC 实际读取的 ConfigMap。这是权威检查——
settings只能说明配置意图:将输出与预期值进行比较。任何其他结果都表示 PAC 未使用你的配置。请注意,如果你有意将该键设置为空字符串(例如清除不再需要的映射),则空输出是正确结果。
常见原因
- 将键写入
settings:operator 的默认值 Webhook 会根据上游 Pipelines as Code 设置结构体重建该映射。Alauda 扩展设置在该结构体中没有对应字段,因此保存时会被静默丢弃,不会产生错误或事件。这会在TektonConfig本身上发生,因此该键甚至不会到达派生 CR。 - 将键写入派生的
OpenShiftPipelinesAsCodeCR:在profile: all上,operator 会在下一次 reconcile 时将settings和options从TektonConfig复制回来,因此即使对于其他情况下会接受的键,该修改也会丢失。 - 直接将键写入 ConfigMap:手动修改会在普通 reconcile 中保留,因为 operator 会将渲染后的 manifest 与哈希注解进行比较,而你的修改不会改变该注解。比较按资源进行,因此不会改变渲染后 ConfigMap 的 PAC 修改(例如
spec.config或 Deployment 选项)会保留该修改。当渲染后的 ConfigMap 本身发生变化时,手动修改会被静默覆盖:对settings或options.configMaps的任何修改、operator 升级,或 installer set 重建都会触发这种情况。因此,手动编辑 ConfigMap 看似生效,但随后会在不可预测的时刻停止生效。
解决方案
将该键移至 TektonConfig 中的 options.configMaps。operator 会按键将其合并到 ConfigMap 中,并且不会重写这些内容:
然后重复第 3 步,确认该值已写入 ConfigMap。详细信息和完整键列表请参阅每个设置的放置位置。
获取帮助
如果你仍然遇到问题:
- 查看日志:检查所有组件日志中的错误
- 验证配置:仔细检查所有配置文件
- 查看文档:查看本指南中的 PAC 文档
- 查看故障排除:查看本文档中的其他故障排除部分
后续步骤
- 管理 PAC 组件 - 部署和管理指南
- 指南 - 仓库设置演练
- 触发 PAC Pipelines - 自动事件和评论命令
- 配置自定义证书 - 信任自签名或私有 CA Git 提供商
- 通过 TektonConfig 配置增强功能 - 自动 Webhook 注册设置