github-runner 是一套面向自托管 GitHub Actions Runner 的技能资料，用于部署、管理和排查执行 CI/CD 工作流作业的机器。自托管 Runner 让用户掌控硬件、操作系统和工具链，代价是需要自行维护运行环境。
用途与触发场景 资料按用户意图组织内容：需要为项目搭建 CI 或为仓库/组织部署自托管 Runner 时，查阅部署部分并选择 systemd、Docker 或 ARC；Runner 无法注册或持续失败、出现 404、注册令牌过期时，查阅管理部分了解 ACCESS_TOKEN 与 RUNNER_TOKEN、分组等；需要自动扩缩容、应对排队作业过多时，查阅扩缩容部分（ARC、Scale Set Client、临时 Runner）；需要安全加固、了解公开仓库风险时，查阅安全部分；需要自定义 Runner 镜像时，查阅自定义镜像部分；需要了解 Runner 需访问的域名、防火墙规则、TLS 与代理时，查阅网络部分；需要标签、分组或两者结合进行作业路由时，查阅管理部分的标签与分组章节；需要监控或排查 Runner 离线、不接收作业等问题时，查阅管理部分的监控与故障排查章节。
部署方式 资料给出四种部署方式的对比：systemd 服务复杂度低、手动扩缩容，适合单机简单 CI；Docker 容器复杂度中等、可手动复制副本，适合家庭实验室或小团队；ARC（Kubernetes）复杂度高、内置自动扩缩容，适合具备 K8s 经验的团队；Scale Set Client 复杂度高、需自定义扩缩容，适合非 K8s 平台团队。
关键概念：ACCESS_TOKEN 与 RUNNER_TOKEN 这是最常见的配置失败点。myoung34/github-runner Docker 入口在启动时会 unexport RUNNER_TOKEN，它仅用于注销；注册需要 ACCESS_TOKEN（GitHub PAT）。ACCESS_TOKEN 用于注册，通过 GitHub API 生成新令牌，长期有效；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 去除操作系统/架构自动标签。
常见陷阱 资料列出若干问题及原因与修复：向 runner-registration 发 POST 返回 404，原因是误用 RUNNER_TOKEN 而非 ACCESS_TOKEN，应改用带 PAT 的 ACCESS_TOKEN；提示找不到名为 Default 的自托管 Runner 分组，原因是组织使用了不同分组名，应通过 gh api 检查分组并设置 RUNNER_GROUP；不想要临时模式却提示已启用，原因是 EPHEMERAL=0 在 bash 中为真值，应使用字符串 EPHEMERAL=false；docker compose down -v 会清除凭据，因为命名卷被删除，使用 ACCESS_TOKEN 可自动恢复；Runner 看不到宿主机文件系统路径，因为运行在 Docker 容器内，应在工作流中内联写入部署配置；Hugo 构建报 Go not found，因为 Ubuntu 20.04 Runner 无 Go，应执行 hugo mod vendor 并提交 _vendor/；GHCR 拉取报 unauthorized，因为部署作业缺少 Docker 仓库认证，应添加 docker/login-action@v4；Runner 离线超过 14 天会被 GitHub 自动移除，需重新注册。
使用流程 资料建议的顺序为：选择部署方式（systemd、Docker、ARC 或 Scale Set Client）；确定 Runner 作用域（仓库级需管理员权限，组织级需组织所有者权限，企业级需企业权限）；注册 Runner（参考架构文档中的注册流程）；用 runs-on 配合标签和可选分组将作业路由到 Runner；出现问题时查阅管理部分的故障排查；生产部署时规划安全与扩缩容。
模板与参考文件 模板包括 templates/docker-compose.yml（使用 myoung34/github-runner 的 Docker Runner）和 templates/custom-runner.Dockerfile（用于 ARC 的自定义 Runner 镜像）。参考文件按需加载：references/architecture.md 用于理解注册流程、作业生命周期或 Runner 通信；references/deployment.md 用于部署 Runner；references/security.md 用于加固、临时/JIT、分组配置；references/scaling.md 用于自动扩缩容；references/management.md 用于分组、标签、监控、故障排查或清理；references/custom-images.md 用于自定义 Runner Dockerfile 与 ARC Kubernetes 模式；references/network.md 用于防火墙规则、代理配置或连接问题排查。
限制 资料未提供具体收费、价格、平台支持范围或效果承诺等信息。