GitHub Actions Runner Docker 镜像文档

一、镜像概述

该Docker镜像用于在自定义环境中运行GitHub Actions工作流，封装了GitHub Actions Runner核心组件，支持本地、私有环境或隔离网络中执行GitHub Actions作业，无需依赖GitHub官方托管的公共Runner。镜像提供标准化的Runner运行环境，简化自定义Runner的部署与管理，适用于CI/CD流水线集成、本地调试及安全合规场景。

二、核心功能与特性

核心功能

• 完整集成GitHub Actions Runner：支持工作流解析、任务调度、步骤执行及结果上报
• 与GitHub生态无缝对接：通过GitHub API实现Runner注册、作业拉取与状态同步
• 多场景作业处理：兼容命令行、脚本、容器化步骤等主流Actions任务类型

特性

• 跨平台支持：基于Linux系统，兼容amd64/arm64等主流架构
• 轻量级设计：采用Alpine或Debian Slim基础镜像，减小镜像体积
• 灵活配置：通过环境变量自定义Runner名称、标签、工作目录等参数
• 持久化存储：支持挂载Runner配置文件与工作目录，实现状态持久化
• 安全认证：集成GitHub Personal Access Token (PAT) 认证机制，支持私有仓库访问
• 动态注册/注销：自动完成Runner注册流程，支持优雅注销（需配置生命周期管理）

三、使用场景与适用范围

适用场景

• 本地调试：开发阶段在本地环境调试GitHub Actions工作流，复现线上问题
• 私有环境部署：企业内部隔离网络（如内网、无公网访问环境）运行Actions，满足数据不出境合规要求
• 自定义CI/CD流水线：作为私有Runner集成到现有CI/CD系统，替代GitHub官方托管Runner
• 教育与学***：学***GitHub Actions运行机制，分析工作流执行过程
• 资源密集型任务：运行需要高CPU/内存的作业（如大型构建、测试），利用本地硬件资源

适用范围

• GitHub.com公共仓库/私有仓库
• GitHub Enterprise Server (GHES) 私有部署环境
• 支持Docker的Linux/macOS/Windows（WSL2）系统
• 需要自定义Runner标签、网络策略或安全隔离的场景

四、使用方法与配置说明

4.1 前提条件

• 已安装Docker Engine（20.10+）及Docker Compose（可选，用于编排）
• 拥有目标GitHub仓库的管理员权限（用于创建Personal Access Token）
• GitHub Personal Access Token（PAT）需具备 repo 和 workflow 权限（创建路径：GitHub账号 → Settings → Developer settings → Personal access tokens → Generate new token）

4.2 获取镜像

从Docker Registry拉取镜像（以镜像名称github-actions-runner为例，实际需替换为具体镜像源）：

docker pull [镜像源地址]/github-actions-runner:latest

若使用私有仓库，需先登录：docker login [私有仓库地址]

4.3 基本使用

4.3.1 快速启动（docker run）

通过docker run命令启动Runner，核心参数包括环境变量（认证与配置）和数据卷（持久化配置）：

docker run -d \
  --name github-runner \
  -e GITHUB_REPOSITORY="owner/repo" \  # 目标仓库（格式：用户名/仓库名）
  -e GITHUB_TOKEN="ghp_xxx" \          # GitHub PAT（需repo、workflow权限）
  -e RUNNER_NAME="my-local-runner" \   # Runner名称（自定义）
  -e RUNNER_LABELS="local,linux,x64" \ # Runner标签（用于工作流选择，逗号分隔）
  -v /path/on/host/runner-data:/runner \  # 挂载Runner配置目录（持久化注册信息）
  --restart unless-stopped \           # 异常退出后自动重启
  [镜像源地址]/github-actions-runner:latest

4.3.2 查看Runner状态

• 容器运行状态：docker ps | grep github-runner
• Runner日志：docker logs -f github-runner（可查看注册过程、作业执行日志）
• 确认Runner在线：登录GitHub仓库 → Settings → Actions → Runners，查看 Runner 状态为“在线”

4.4 环境变量配置

镜像通过环境变量控制Runner行为，以下为核心变量说明：

4.5 docker-compose配置

通过docker-compose.yml管理Runner部署，支持多实例、依赖管理等场景：

version: '3.8'

services:
  github-runner:
    image: [镜像源地址]/github-actions-runner:latest
    container_name: github-runner
    restart: unless-stopped
    environment:
      - GITHUB_REPOSITORY=my-org/my-project
      - GITHUB_TOKEN=${GITHUB_TOKEN}  # 建议通过宿主机环境变量传入，避免硬编码
      - RUNNER_NAME=staging-runner
      - RUNNER_LABELS=staging,linux,x64
      - RUNNER_WORKDIR=/workspace
      - HTTP_PROXY=[***]
    volumes:
      - ./runner-data:/runner  # 持久化Runner配置（注册信息、证书等）
      - ./workspace:/workspace # 挂载自定义工作目录（可选）
    deploy:
      resources:
        limits:
          cpus: '2'    # 限制CPU核心数
          memory: 4G   # 限制内存使用

启动命令：GITHUB_TOKEN=ghp_xxx docker-compose up -d

4.6 高级配置

4.6.1 持久化与数据管理

• Runner配置文件：通过-v /host/path:/runner挂载/runner目录，持久化Runner注册信息（避免容器重建后需重新注册）。
• 工作目录：通过RUNNER_WORKDIR指定作业执行目录，建议挂载宿主机目录（如-v /host/workdir:/workspace），避免容器内存储满导致作业失败。

4.6.2 组织级Runner部署

支持为GitHub组织注册Runner（所有仓库共享），需修改GITHUB_REPOSITORY为组织名（格式：org/组织名），并确保GITHUB_TOKEN具备admin:org权限：

docker run -d \
  -e GITHUB_REPOSITORY="org/my-company" \  # 组织级Runner
  -e GITHUB_TOKEN="ghp_xxx" \              # 需admin:org权限
  -e RUNNER_GROUP="shared-runners" \       # 组织Runner组
  -v /host/runner-data:/runner \
  [镜像源地址]/github-actions-runner:latest

五、配置参数说明

除环境变量外，可通过命令行参数或挂载配置文件调整高级行为（需镜像支持）：

5.1 命令行参数（通过docker run命令传递）

• --unattended：非交互式模式（默认启用，适合容器环境）
• --ephemeral：临时Runner（作业完成后自动注销，避免资源占用），需镜像支持EPHEMERAL_RUNNER=true环境变量
• --replace：替换同名Runner（若已存在同名Runner，先注销再注册）

5.2 自定义Entrypoint

如需覆盖默认启动脚本（如添加前置初始化步骤），可通过--entrypoint指定自定义脚本：

docker run -d \
  --entrypoint /custom-entrypoint.sh \
  -v ./custom-entrypoint.sh:/custom-entrypoint.sh \
  ...  # 其他参数

六、注意事项

1. 令牌安全性：GITHUB_TOKEN需严格保密，禁止硬编码到脚本或镜像中，建议通过Docker Secrets、Kubernetes Secrets或CI/CD平台的环境变量管理（如GitHub Actions Secrets、GitLab CI Variables）。
2. Runner生命周期：容器停止后，Runner会显示为“离线”，重启容器可恢复在线状态；若需永久删除Runner，需手动在GitHub仓库/组织的Runner页面点击“移除”。
3. 资源限制：根据作业类型配置CPU/内存限制（如--cpus 2 --memory 4g），避免Runner占用过多宿主机资源。
4. 网络隔离：若Runner需访问内网服务，可通过--network host或自定义Docker网络实现网络打通。
5. 镜像更新：定期更新镜像至最新版本，以获取Runner安全补丁和功能更新（GitHub Runner定期发布更新，旧版本可能被禁用）。

七、故障排查

• Runner注册失败：检查GITHUB_TOKEN权限（需repo和workflow权限）、GITHUB_REPOSITORY格式是否正确、网络是否可访问api.github.com。
• 作业执行失败：查看容器日志（docker logs <容器名>），检查作业步骤输出；确认Runner标签与工作流runs-on匹配。
• 持久化数据损坏：删除挂载的/runner目录，重新启动容器（会重新注册Runner，原Runner需手动在GitHub上移除）。