GitHub Actions 配置参数详解

目标：系统梳理 GitHub Actions 自托管 Runner 的配置参数，覆盖 config.sh 全部参数、.env 环境文件、.path、labels 标签体系、自托管 Runner 组、仓库 Secrets/Variables 管理，并给出实测默认值与修改方式。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• Runner 版本：2.338.0（安装见《Ubuntu 22.04 安装 GitHub Actions Runner 指南》）
• 安装目录：/opt/data/github-actions/actions-runner
• 数据目录：/opt/data/github-actions
• Runner 运行用户：root（需 RUNNER_ALLOW_RUNASROOT=1）
• 仓库示例：https://github.com/quzuo-ops/demo-app
• 服务管理：./svc.sh 生成 systemd 服务

💡 说明：下表"实测默认值"来自本机 Runner 2.338.0 的真实 --help 输出与安装目录文件（.env/.path）读取，与官方默认一致，便于读者对照。

二、前置条件

• 已按《Ubuntu 22.04 安装 GitHub Actions Runner 指南》完成 Runner 2.338.0 安装
• 拥有 root 权限（配置以 root 运行时需 RUNNER_ALLOW_RUNASROOT=1）
• 具备仓库 Settings 管理权限（配置 Secrets/Variables 与 Runner 组时）
• 需要一个注册 Token（部署新 Runner）或已注册的 Runner（改参数）

三、参数查看与修改方式

3.1 config.sh 帮助（参数速查）与修改

所有 config.sh 参数通过命令行传入并在注册时固化，帮助信息如下：

cd /opt/data/github-actions/actions-runner
RUNNER_ALLOW_RUNASROOT=1 ./config.sh --help

实测回显：

Commands:
 ./config.sh         Configures the runner
 ./config.sh remove  Unconfigures the runner
 ./run.sh            Runs the runner interactively. Does not require any options.

Options:
 --help     Prints the help for each command
 --version  Prints the runner version
 --commit   Prints the runner commit
 --check    Check the runner's network connectivity with GitHub server

Config Options:
 --unattended           Disable interactive prompts for missing arguments. Defaults will be used for missing options
 --url string           Repository to add the runner to. Required if unattended
 --token string         Registration token. Required if unattended
 --name string          Name of the runner to configure (default c705af9cc8b2)
 --runnergroup string   Name of the runner group to add this runner to (defaults to the default runner group)
 --labels string        Custom labels that will be added to the runner. This option is mandatory if --no-default-labels is used.
 --no-default-labels    Disables adding the default labels: 'self-hosted,Linux,X64'
 --local                Removes the runner config files from your local machine. Used as an option to the remove command
 --work string          Relative runner work directory (default _work)
 --replace              Replace any existing runner with the same name (default false)
 --pat                  GitHub personal access token with repo scope. Used for checking network connectivity when executing `./run.sh --check`
 --disableupdate        Disable self-hosted runner automatic update to the latest released version`
 --ephemeral            Configure the runner to only take one job and then let the service un-configure the runner after the job finishes (default false)

💡 说明：参数在注册时一次性写入；改动需用 --replace 重新配置，或删掉 .credentials/.runner 后重新注册。--help 仅展示参数，不能运行时热改。

3.2 config.sh 常用组合示例

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --unattended \
  --url https://github.com/quzuo-ops/demo-app \
  --token <TOKEN> \
  --name demo-runner \
  --runnergroup default \
  --labels self-hosted,Linux,X64,demo \
  --work _work \
  --replace

⚠️ 说明：<TOKEN> 为占位，实际请填入仓库设置页生成的注册 Token（有效期 1 小时），详见安装指南"六、注册"。

3.3 .env 环境文件

.env 是 runner 根目录下的 KEY=VALUE 环境文件，注册后写入固定环境项（如机器级 env）。初始状态为空：

cat /opt/data/github-actions/actions-runner/.env

实测回显（初始为空）：

💡 说明：.env 内的行会被追加到每次 job 的进程环境中，适合持久化自定义变量（如 MY_ORG_ENV=stable）。修改后用 ./svc.sh restart 生效。

3.4 .path 系统 PATH

.path 存放 runner 工作流进程可用的 PATH，初始为系统默认：

cat /opt/data/github-actions/actions-runner/.path

实测回显：

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

💡 说明：可在配置后追加自定义二进制目录（如 Java 的 bin），使工作流内 run 步骤无需写全路径即可调用。

四、参数总览

五、config.sh 核心参数详解

5.1 名称 --name

Runner 在 GitHub 页面展示的名称，同一仓库内需唯一。多个 Runner 务必用 --name 区分，避免与默认主机名冲突。

5.2 标签 --labels / --no-default-labels

标签用于 runs-on 匹配 self-hosted Runner。默认自带 self-hosted,Linux,X64；--labels 追加自定义标签（逗号分隔），--no-default-labels 则只保留你显式给出的标签。

runs-on: [self-hosted, cuda]     # 工作流据此挑选带 cuda 标签的 Runner

⚠️ 规则：一旦使用 --no-default-labels，--labels 为必填项（config.sh --help 明确标注 "This option is mandatory if --no-default-labels is used"）。标签区分大小写。

5.3 工作目录 --work

_work 是 job 的默认工作区父目录，run 步骤的 $GITHUB_WORKSPACE 在其下。放独立数据盘可避免根分区写满：

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --unattended \
  --url https://github.com/quzuo-ops/demo-app --token <TOKEN> \
  --name demo-runner --work /opt/data/github-actions/_work

5.4 更新策略 --disableupdate / 一次性 --ephemeral

• --disableupdate：禁止 runner 自动更新到最新发布版，适合对版本锁定出厂环境的场景；
• --ephemeral：runner 只取一个 job，结束后自动注销，适合弹性伸缩场景，每次任务干净隔离。

5.5 覆盖注册 --replace

已存在同名 Runner 时，config.sh 默认拒绝；加 --replace 干掉旧实例重配。日常改参数重配时必带。

5.6 连通性检查 --pat

配合 run.sh --check 检测 runner 到 GitHub 的连通性，需有效 ghp_ PAT：

RUNNER_ALLOW_RUNASROOT=1 ./run.sh --check \
  --url https://github.com/quzuo-ops/demo-app --pat <GH_PAT>

六、自托管 Runner 组（Runner Group）

Runner 组用于给多个 Runner 划分访问范围（组织级）或限定仓库（仓库级），实现权限隔离与负载池化。

• 仓库级默认组：default（新仓库 Runner 都在此组）；
• 组织级 Runner 组可在组织 Settings → Actions → Runner groups 创建；
• --runnergroup 指定将 Runner 加入的组，未指定放入 default：

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --unattended \
  --url https://github.com/quzuo-ops/demo-app --token <TOKEN> \
  --name demo-runner --runnergroup dev-pool

💡 说明：只有被加入该 Runner 组的仓库/组织才能把 job 调度到其内 Runner，实现"谁可用这组机器"的细粒度控制。

七、仓库 Secrets 与 Variables

7.1 Secrets（机密）

• 存放位置：仓库 Settings → Secrets and variables → Actions → Secrets
• 引用：工作流 env: 内用 ${{ secrets.API_TOKEN }}，后续以环境变量使用
• 特点：只写不可读，历史值不可查，日志自动打码 ***
• 组织级 Secrets 可同时给多个仓库用；公共仓库仅限付费计划组织内使用

7.2 Variables（变量）

• 存放位置：同页面 Variables 标签
• 引用：${{ vars.APP_VERSION }}
• 特点：明文可读，适合非敏感的版本号、环境名等

steps:
  - name: 打印变量
    run: echo "版本 ${{ vars.APP_VERSION }}"
    env:
      APP_VERSION: ${{ vars.APP_VERSION }}
      TOKEN: ${{ secrets.API_TOKEN }}

⚠️ 命名约定：Secrets 名称不区分大小写，但引用时建议统一大写；不要用空格或保留关键字。

八、实测：路由到指定标签

已验证 runs-on: [self-hosted, <label>] 的匹配逻辑——只有带对应标签的 Runner 会被调度。相关比对见下表：

九、常见问题

Q1：改 labels 后工作流还匹配不上？

重新注册并加 --replace 刷新标签，再确认工作流 runs-on 标签拼写与大小写一致。

Q2：runner 处于 Busy 状态无法修改？

等到当前 job 结束，或 ./svc.sh stop 停服务后再重配与 ./svc.sh start。

Q3：--no-default-labels 报标签缺失？

使用该参数时必须同时 --labels 显式给出（帮助里明确标注 mandatory）。

Q4：Secrets 打码不生效 / 日志泄漏？

确认 secrets 是通过 env: 传入后以变量引用，而不是在 run: 命令里 echo ${{ secrets.X }} 直接回显，后者可能被抓进日志。

十、原理解析（配置落盘位置）

• .credentials / .runner：注册文件，含 runner 标识与凭据；
• .service：由 ./svc.sh install 写入的服务名；
• .env / .path：环境与 PATH 覆盖；
• _diag/：运行与诊断日志。
• 卸载恢复出厂：删除 .credentials 与 .runner 后重新 config.sh 即可。

十一、参考链接

• 自托管 Runner 配置：https://docs.github.com/zh/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners
• Runner 分组：https://docs.github.com/zh/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow
• Secrets 与 Variables：https://docs.github.com/zh/actions/security-guides/using-secrets-and-variables
• config.sh 帮助：./config.sh --help（本机实测）