GitLab CI执行流水线报gcloud: command not found部署失败如何解决

报错gcloud: command not found的核心原因是当前使用的Shell类型GitLab Runner执行节点上，无法找到gcloud可执行程序，常见触发场景有两类：

1. Runner所在宿主机未安装Google Cloud SDK（gcloud命令行工具）
2. 已经安装SDK，但gcloud的可执行文件路径没有加入gitlab-runner运行用户的PATH环境变量，或是gitlab-runner用户对SDK安装目录没有读取、执行权限，执行脚本时无法定位到命令。
   由于使用的是Shell执行器，所有CI脚本里用到的命令都依赖Runner宿主机的本地环境，不会像Docker执行器那样自动拉取带预装依赖的镜像，本地环境缺依赖就会直接报错。

• 第一步定位执行节点：从日志可以看到作业跑在标签为3wNvyH89的ci runner上，对应宿主机是localhost.localdomain，直接登录这台机器操作。
• 切换到gitlab-runner运行用户，执行gcloud version验证命令是否可用：
  • 如果直接提示command not found，先确认机器是否安装Google Cloud SDK，没装的话按系统对应版本安装到全局可访问路径（比如/usr/local/目录下），不要只装在root或某个个人用户的私有目录里。
  • 如果其他用户（比如root）下能正常执行gcloud，只有gitlab-runner用户下找不到，就是PATH配置问题：先在能正常执行gcloud的用户下运行which gcloud拿到gcloud的完整目录，默认安装路径一般是/usr/lib/google-cloud-sdk/bin/。
• 修复路径配置，二选一即可：
  1. 全局修复：编辑gitlab-runner用户家目录下的.bashrc文件，追加一行export PATH=$PATH:<你查到的gcloud所在bin目录路径>，保存后重新加载shell配置，再切gitlab-runner用户验证gcloud version能正常输出版本即可。
  2. CI脚本内临时修复：在.gitlab-ci.yml的部署作业里，执行gcloud命令前先追加PATH，示例配置：

     script:
       - export PATH=$PATH:/usr/lib/google-cloud-sdk/bin # 替换成你实际的gcloud bin路径
       - echo $SERVICE_ACCOUNT > /tmp/$CI_PIPELINE_ID.json
       - gcloud auth activate-service-account --key-file /tmp/$CI_PIPELINE_ID.json
       # 后续保留原有的部署脚本逻辑
     

• 权限校验：确认gcloud的安装目录权限对gitlab-runner用户开放读取和执行权限，不要把目录权限设为仅root可访问，否则就算路径加对了也会因为读不到文件报命令不存在。
• 所有配置改完后，切到gitlab-runner用户本地验证gcloud命令可以正常执行，再重跑失败的流水线即可。

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