GitHub Actions Runner 镜像文档

镜像概述

GitHub Actions Runner 镜像是用于执行GitHub Actions工作流中作业的容器化应用程序，是GitHub Actions生态系统的核心组件之一。它负责接收并运行工作流文件中定义的自动化任务，支持各类CI/CD操作，如代码构建、测试执行、应用部署等，为软件开发流程提供自动化执行环境。

核心功能与特性

• 工作流作业执行：接收并执行GitHub仓库中定义的GitHub Actions工作流作业，支持YAML配置文件中指定的所有步骤和命令
• GitHub Actions集成：与GitHub平台无缝对接，自动接收作业分配、汇报执行状态及结果
• 容器化隔离：以Docker容器形式运行，提供独立的执行环境，避免与主机系统或其他任务产生环境冲突
• 跨平台兼容性：支持在主流操作系统（Linux、Windows、macOS）的Docker环境中部署运行
• 资源可控：可通过Docker配置限制CPU、内存等资源使用，适应不同规模的任务需求

使用场景与适用范围

• 个人项目自动化：用于个人GitHub仓库的CI/CD流程，实现代码提交后的自动构建、测试和部署
• 团队协作开发：在团队项目中统一执行环境，确保所有成员的工作流在一致条件下运行
• 企业级DevOps：满足企业内部对自动化流程的定制化需求，可部署在私有环境中保障数据安全
• 多任务并行处理：通过部署多个Runner实例，支持同时执行多个工作流作业，提升自动化效率
• 特殊环境需求：为需要特定依赖或工具版本的工作流提供定制化执行环境

使用方法与配置说明

前提条件

• 已安装Docker引擎（推荐版本20.10及以上）
• 拥有GitHub账号及目标仓库的管理员权限（用于获取Runner注册令牌）
• 网络环境可访问GitHub API服务（[***]

Docker运行命令示例

通过docker run直接启动Runner容器：

bash
docker run -d \
  --name github-actions-runner \
  -e REPO_URL="[***][用户名]/[仓库名]" \
  -e RUNNER_TOKEN="[Runner注册令牌]" \
  -e RUNNER_NAME="docker-runner-01" \
  -e RUNNER_LABELS="docker,linux,x64" \
  --restart unless-stopped \
  github/runner:latest

Docker Compose配置示例

创建docker-compose.yml文件：

yaml
version: '3.8'
services:
  github-runner:
    image: github/runner:latest
    container_name: github-actions-runner
    environment:
      - REPO_URL=[***][用户名]/[仓库名]
      - RUNNER_TOKEN=[Runner注册令牌]
      - RUNNER_NAME=docker-runner-01
      - RUNNER_LABELS=docker,linux,x64
      - RUNNER_WORKDIR=/home/runner/work
    volumes:
      - runner-workdir:/home/runner/work
    restart: unless-stopped

volumes:
  runner-workdir:

启动服务：

bash
docker-compose up -d

核心配置参数说明

注册与管理流程

1. 获取Runner注册令牌

1. 进入GitHub仓库 → Settings → Actions → Runners
2. 点击 New self-hosted runner，选择操作系统类型为Linux
3. 在"Download"步骤后，复制"Configure"部分的临时注册令牌（格式为AXXXXXXX...）

2. 启动与注册

启动容器后，Runner会自动使用提供的REPO_URL和RUNNER_TOKEN完成注册，注册成功后可在GitHub仓库的Runner列表中看到该实例，状态显示为"Idle"

3. 状态监控与管理

• 查看容器日志：docker logs -f github-actions-runner
• 停止Runner：docker stop github-actions-runner
• 注销Runner：在GitHub仓库Runner列表中找到对应实例，点击Remove

注意事项

• 注册令牌有效期为60分钟，过期后需重新生成并更新环境变量
• 生产环境建议使用持久化卷（Volume）挂载工作目录，避免容器重启后丢失作业数据
• 确保容器时间与GitHub服务器时间同步，避免因时间偏差导致的认证问题
• 定期更新镜像版本（docker pull github/runner:latest）以获取安全更新和功能改进
• 敏感环境中建议限制容器网络访问，仅允许与GitHub API及必要服务通信