GitHub Actions工作流参数化配置runs-on字段的问题排查

runs-on是GitHub Actions工作流调度前校验阶段就必须完成解析的字段，这个阶段GitHub只会加载极有限的上下文：

• 你之前尝试引用的secrets、工作流根级env上下文，都是在runner分配完成、工作流正式启动执行阶段才会加载，校验阶段根本不存在，所以会抛出Unrecognized named-value的语法错误。
• 你尝试用$RUNNER_LABEL这种shell变量写法也不可能生效：runs-on是YAML配置层面的字段解析，完全不会进入shell执行逻辑，这种写法相当于GitHub会去找一个标签名就叫$RUNNER_LABEL的runner，自然一直卡调度无法运行。

你的核心诉求是统一收敛runner标签配置、避免批量修改工作流文件，且标签值不需要加密，优先选下面两个原生方案：

方案1：使用仓库/组织级公开配置变量（最简便，零改造成本） #

GitHub专门为不需要加密的可复用配置提供了vars上下文，这个上下文是在工作流校验阶段就可以正常读取的，完全支持在runs-on字段直接引用：

1. 配置入口：
   • 单仓库生效：进入仓库Settings->Secrets and variables->Actions->切换到Variables标签页，新建变量名为GH_RUNNER_TAG，值填你需要的runner标签即可。
   • 组织下全仓库生效：进入组织Settings->Actions->Variables，新建同名变量，配置可见范围覆盖需要用到的仓库即可。
2. 工作流中直接引用，不需要额外做env中转：

   jobs: 
     process:
       name: Process
       runs-on: ${{ vars.GH_RUNNER_TAG }}
   

后续要更换runner标签时，只需要修改变量值，所有引用该变量的工作流会自动生效，不需要逐个修改YAML文件。

方案2：使用可复用工作流收敛配置（适合后续有更多统一配置需求的场景） #

如果后续你还需要统一维护其他工作流通用逻辑（比如前置检查、默认步骤、权限配置等），可以把runner配置收敛到一个公共的可复用工作流中，其他所有业务工作流统一调用这个公共文件，后续修改只需要更新公共文件即可：

1. 新建公共可复用工作流，例如存为.github/workflows/_base_runner.yml：

   on:
     workflow_call:
       inputs:
         # 支持特殊场景下自定义覆盖runner标签，默认走统一配置
         runner_tag:
           type: string
           required: false
           default: 'your-default-runner-label'
   jobs:
     run_task:
       runs-on: ${{ inputs.runner_tag }}
       steps:
         # 这里可以放所有工作流通用的前置步骤，比如代码拉取、环境初始化等
         - uses: actions/checkout@v4
         # 也可以配置支持传入自定义步骤，满足不同业务的个性化需求
   

2. 其他业务工作流不需要单独配置runs-on，直接调用公共工作流即可：

   jobs:
     process:
       uses: ./.github/workflows/_base_runner.yml
       # 特殊场景需要用专属runner时再传参覆盖，默认不需要传
       # with:
       #   runner_tag: 'gpu-special-runner'
   

不要尝试用secrets或者工作流根级env给runs-on传值，这两类值的解析时机晚于runner调度逻辑，从GitHub Actions的设计上就不支持这种用法。

内容的提问来源于stack exchange，提问作者Andrei Rînea