如何配置Github Action自托管Runner自定义环境变量避免被覆盖？

问题背景 #

自托管 Runner 执行 Shell 时默认带 --no-profile --norc 参数，跳过了系统 shell 配置文件（profile/bashrc）的加载，同时自带的环境变量校验机制（env.sh 里的 varCheckList）会过滤非白名单变量，导致常规方式添加的环境变量要么不生效，要么被覆盖。

可行解决方案 #

1. 直接修改 Runner 根目录的 .env 文件

这是最稳妥的全局方案，Runner 启动时会自动加载该文件的变量，且不会被覆盖（只要变量名不与 Runner 核心内置变量冲突）。

• 找到你的 Runner 安装目录（比如 ./actions-runner），编辑其中的 .env 文件
• 添加自定义变量，格式如下：

MY_CUSTOM_VAR=my-custom-value
DB_CONN_STRING=postgres://user:pass@localhost:5432/db

• 重启 Runner 即可生效

2. 调整 env.sh 的 varCheckList（需注意更新覆盖）

如果你的变量被 varCheckList 过滤，可以手动将其加入白名单：

• 打开 Runner 安装目录下的 bin/env.sh 文件
• 找到 varCheckList 数组，将你的自定义变量名添加进去：

varCheckList=(
    "PATH"
    "LANG"
    "HOME"
    "MY_CUSTOM_VAR"  # 新增自定义变量
)

⚠️ 注意：Runner 版本更新后，这个文件会被覆盖，需要重新修改。

3. 工作流内临时定义（仅单工作流生效）

如果只是特定工作流需要该变量，直接在 workflow YAML 中定义：

jobs:
  deploy:
    runs-on: self-hosted
    env:
      MY_CUSTOM_VAR: temp-value
    steps:
      - name: 打印自定义变量
        run: echo $MY_CUSTOM_VAR

避坑提示 #

• 不要尝试在 profile/bashrc 中添加变量，Runner 执行 Shell 时会跳过这些文件的加载，完全无效
• 自定义变量不要使用 RUNNER_、ACTIONS_ 开头，这类前缀属于 Runner 内置变量，会被强制覆盖

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