自建GitLab Runner半数情况下无法识别PowerShell命令问题排查

在Windows Server 2016上部署自建GitLab Runner，config.toml已明确指定shell = "powershell"，但新建流水线时约半数情况会出现Runner“忘记”使用PowerShell的问题：

• 失败时脚本尝试用Bash执行（输出中出现bash标识），导致Remove-Item: command not found错误
• 无需修改任何配置，重试几次后流水线又能正常运行（成功时无bash标识，使用PowerShell执行）
• 每次新增Runner时，必须手动将默认生成的shell = "pwsh"改为shell = "powershell"，否则Runner完全无法运行

当前使用的Runner配置（config.toml）：

concurrent = 1
check_interval = 0
log_level = "debug"

[session_server]
  session_timeout = 1800

[[runners]]
  name = "Application Template"
  url = "https://my-gitlab-instance.com"
  token = "mYt0k3n"
  executor = "shell"
  shell = "powershell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

故障流水线的deploy任务配置：

deploy-job:
  stage: deploy
  dependencies: 
    - build-job
  environment: production
  script:
    - 'Remove-Item -Path "$env:DEPLOY_PATH\*.*"'
    - 'xcopy /y /s ".\public\*.*" "$env:DEPLOY_PATH"'

这种时有时无的shell切换问题，通常是Runner配置未完全生效、环境冲突或版本bug导致，可按以下步骤排查修复：

1. 确保Runner配置修改后重启服务 #

修改config.toml后，必须重启GitLab Runner服务才能让配置完全生效：

• 打开Windows服务管理器（services.msc），找到GitLab Runner服务，右键选择「重启」
• 或用PowerShell执行命令：

  Restart-Service gitlab-runner
  

2. 在流水线中强制指定shell #

在.gitlab-ci.yml中添加全局默认shell配置，避免Runner偶尔 fallback到默认的Bash：

default:
  shell: powershell

deploy-job:
  stage: deploy
  dependencies: 
    - build-job
  environment: production
  script:
    - 'Remove-Item -Path "$env:DEPLOY_PATH\*.*"'
    - 'xcopy /y /s ".\public\*.*" "$env:DEPLOY_PATH"'

3. 检查环境变量冲突 #

确认服务器上没有设置GITLAB_RUNNER_SHELL环境变量：

• 打开系统属性 → 高级 → 环境变量，检查系统变量和用户变量中是否存在该变量，若存在且值为bash则删除

4. 验证PowerShell路径配置 #

确保powershell.exe的路径在系统PATH中：

• 打开CMD执行where powershell，应返回C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
• 若未找到，将该路径添加到系统PATH环境变量中

5. 注册Runner时直接指定shell #

新增Runner时，通过命令行参数直接指定--shell powershell，避免默认生成pwsh配置：

gitlab-runner register --url "https://my-gitlab-instance.com" --token "mYt0k3n" --name "Application Template" --executor shell --shell powershell

6. 更新GitLab Runner到稳定版本 #

旧版本Runner在Windows环境下可能存在shell选择的bug，下载最新稳定版重新安装：

• 卸载现有Runner，下载对应Windows版本的安装包重新安装，安装完成后重启服务

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