本地正常的Shell脚本在GitLab Runner中执行失败排查

1. 环境变量TAG未正确赋值或为空 #

GitLab Runner中TAG变量可能未被正确传递（比如未在CI/CD变量中配置、变量名拼写错误），导致jq表达式中的$TAG为空字符串，无法匹配到任何镜像标签。

• 排查：在关键jq命令前添加echo "TAG value is: $TAG"，查看变量实际取值。
• 修复：确保TAG变量在GitLab CI/CD配置中正确定义，或在脚本内显式赋值。

2. curl返回的JSON结构与本地不一致 #

虽然JSON格式合法，但本地和Runner环境中Harbor API返回的JSON结构可能存在差异：

• 例如本地直接返回镜像列表数组，而Runner中返回的是包裹数组的对象（如{"items": [/* 镜像列表 */]}），此时.[]无法正确遍历目标数组，需改为.items[]。
• 排查：在脚本中添加echo "$response"，对比本地和Runner返回的JSON内容结构。
• 修复：根据实际JSON结构调整jq表达式，同时可添加?避免空字段报错，例如：.items[]|select(.tags[]?.name==$TAG)。

3. jq筛选表达式存在潜在报错逻辑 #

当前表达式.[]|select(.tags[].name==$TAG)在遇到无tags字段或tags为空数组的镜像时，会触发jq错误，导致非零退出码：

• 本地环境的JSON可能所有镜像都包含有效tags字段，但Runner拿到的JSON中存在无tags的镜像，直接导致表达式执行报错。
• 修复：改用更严谨的any()函数，只要存在匹配项就返回true，同时避免遍历报错：

  echo "$response" | jq -e --arg TAG "$TAG" 'any(.[]; .tags[]?.name == $TAG)' > /dev/null
  

4. Shell环境差异 #

本地使用bash而GitLab Runner默认使用sh（dash），部分bash专属特性可能不兼容：

• 比如PIPESTATUS是bash专属变量，虽用户用它验证了JSON格式，但脚本其他部分可能存在sh不兼容写法；另外不同Shell对echo特殊字符的处理也可能有差异。
• 排查：在CI脚本开头添加echo "$SHELL"查看当前Shell，或强制指定bash执行脚本（GitLab CI配置中用script: ["bash", "-c", "你的脚本内容"]）。
• 修复：将脚本改为兼容POSIX sh的写法，或在CI配置中指定使用bash。

5. Harbor权限差异导致返回内容不同 #

本地使用的Harbor账号权限更高，能看到包含目标TAG的镜像，而Runner使用的账号权限不足，返回的镜像列表中无目标TAG条目，导致jq筛选无结果：

• 排查：在Runner中执行echo "$response"，检查返回的镜像列表是否包含目标TAG的条目。
• 修复：确保Runner使用的Harbor账号拥有对应镜像仓库的读取权限。

内容的提问来源于stack exchange，提问作者IFThenElse