github-runner

自托管 GitHub Actions 运行器

部署和管理自托管 GitHub Actions 运行器——执行 CI/CD 工作流任务的机器。自托管运行器让你可以控制硬件、操作系统和工具链，但你需要自行维护环境。

适用场景

触发语句	操作
“为我的项目设置 CI”，“为 [仓库/组织] 部署自托管运行器”	阅读部署——选择 systemd、Docker 或 ARC
“运行器无法注册／持续失败”，“运行器返回 404”，“注册令牌已过期”	阅读管理——ACCESS_TOKEN 与 RUNNER_TOKEN、组
“如何自动扩缩运行器”，“自动扩缩运行器”，“排队任务太多”	阅读扩缩——ARC、Scale Set Client、临时运行器
“保护我的自托管运行器”，“加固运行器”，“运行器安全”，“公共仓库风险”	阅读安全——公共仓库风险、临时运行器、JIT、组
“创建自定义运行器镜像”，“构建运行器 Dockerfile”，“带 Python 的自定义运行器”	阅读自定义镜像——Dockerfile、ARC 容器模式
“运行器需要访问哪些域名？”，“运行器防火墙规则”，“运行器网络设置”	阅读网络——防火墙规则、TLS、代理
“路由时用标签、组，还是两者都用？”，“如何指定特定运行器”	阅读管理——标签和组章节
“监控／排查运行器问题”，“运行器离线”，“运行器未接收任务”	阅读管理——监控和故障排查章节

快速参考

部署方案

方式	复杂度	自动扩缩	适用场景
systemd 服务	低	手动	单台机器、简单 CI
Docker 容器	中	手动副本	家庭实验室、小型团队
ARC（Kubernetes）	高	内置	具备 K8s 专业知识的团队
Scale Set Client	高	自定义	非 K8s 平台团队

关键事项：ACCESS_TOKEN 与 RUNNER_TOKEN

这是最常见的配置失败原因。myoung34/github-runner Docker 入口点在启动时取消导出 RUNNER_TOKEN——它仅用于注销。注册需要 ACCESS_TOKEN（GitHub PAT）。

令牌	用途	有效期
ACCESS_TOKEN	注册——通过 GitHub API 生成新令牌	长期有效（PAT）
RUNNER_TOKEN	仅用于注销——不用于初始注册	60 分钟

PAT 权限范围：

• 仓库级：repo
• 组织级：admin:org
• 企业级：manage_runners:enterprise

标签策略

默认标签：self-hosted + 操作系统（linux/windows/macOS）+ 架构（x64/ARM/ARM32/ARM64）

常见约定：self-hosted,<hostname>,<os>,<arch>,<project>。在工作流中：

runs-on: [self-hosted, linux, x64, gpu]

所有标签都必须匹配（AND 逻辑）。使用 --no-default-labels 移除自动添加的操作系统／架构标签。

常见问题

问题	原因	解决方法
POST 请求 runner-registration 时返回 404	使用了 RUNNER_TOKEN 而非 ACCESS_TOKEN	改用带 PAT 的 ACCESS_TOKEN
“Could not find any self-hosted runner group named 'Default'”	组织使用了其他组名	通过 gh api 检查组，并设置 RUNNER_GROUP
未预期出现 “Ephemeral option is enabled”	EPHEMERAL=0 在 bash 中为真值	使用 EPHEMERAL=false（字符串）
docker compose down -v 清除了凭据	命名卷已删除	使用 ACCESS_TOKEN 后可自动恢复
运行器无法访问主机文件系统路径	运行器在 Docker 容器内运行	在工作流中内联编写部署配置
Hugo 构建提示 “Go not found”	Ubuntu 20.04 运行器上没有 Go	执行 hugo mod vendor 并提交 _vendor/
拉取 GHCR 镜像提示 “unauthorized”	部署任务中未进行 Docker 注册表身份验证	添加 docker/login-action@v4
运行器离线超过 14 天	被 GitHub 自动移除	注册新的运行器

顺序工作流

1. 选择部署方式

阅读 deployment，选择 systemd、Docker、ARC 或 Scale Set Client。

2. 确定所需的 Runner 范围

• 仓库级：Runner 的范围为单个仓库 — 你需要管理员访问权限
• 组织级：Runner 在组织内的多个仓库间共享 — 你需要组织所有者访问权限
• 企业级：Runner 在企业内的多个组织间共享 — 你需要企业访问权限

3. 注册 Runner

阅读 architecture 参考文档，了解注册流程。

4. 将作业路由到 Runner

使用 runs-on 搭配标签，并可选择使用组。阅读 management 中有关标签的部分。

5. 监控和排查问题

出现问题时，阅读 management 中的故障排除部分。

6. 规划安全和扩展

对于生产部署，请阅读 security 和 scaling。

模板

• templates/docker-compose.yml — 使用 myoung34/github-runner 的 Docker Runner
• templates/custom-runner.Dockerfile — 用于 ARC 的自定义 Runner 镜像

参考文件

文件	在以下情况下加载
references/architecture.md	你需要了解注册流程、作业生命周期或 Runner 通信
references/deployment.md	你需要部署 Runner — systemd、Docker、ARC 或 Scale Set Client
references/security.md	你需要强化 Runner 安全性、设置临时/JIT 模式或配置组
references/scaling.md	你需要自动扩缩 — ARC、Scale Set Client 或由 webhook 驱动的扩缩
references/management.md	你需要了解组、标签、监控、故障排除或清理
references/custom-images.md	你需要自定义 Runner Dockerfile 或 ARC Kubernetes 模式
references/network.md	你需要配置防火墙规则、代理，或正在排查连接问题