jefriherditriyanto/github-runner

GitHub Actions自托管Runner镜像

镜像概述

本Docker镜像用于运行GitHub Actions自托管runner，并支持**Docker-in-Docker（DinD）**模式。它允许在容器内部直接执行docker build、docker push和docker compose等操作，无需从主机挂载Docker socket，同时提供容器停止时的自动清理功能。

核心功能

• 在容器内启动Docker守护进程（dockerd）
• 自动注册runner到指定的GitHub仓库
• 运行runner以处理GitHub Actions工作流
• 容器停止时（收到SIGTERM/SIGINT信号）自动清理：移除runner并停止dockerd

使用场景

• 需要在自托管环境中运行GitHub Actions工作流，且工作流包含Docker相关操作（如构建、推送镜像）
• 希望隔离Docker环境，避免直接使用主机Docker socket带来的安全风险
• 需要快速部署自托管runner，支持动态扩展CI/CD能力

配置说明

环境变量（必填）

• REPO_URL：GitHub仓库的URL，例如https://github.com/username/repo
• RUNNER_TOKEN：从GitHub获取的runner token（临时有效）

运行要求

• 必须使用--privileged参数启动容器，以确保dockerd能正常运行

部署示例

Docker Run命令

bash
docker run -d \
  --name github-runner \
  --privileged \
  -e REPO_URL=https://github.com/username/repo \
  -e RUNNER_TOKEN=YOUR_TOKEN \
  jefriherditriyanto/github-runner:latest

Docker Compose配置

yaml
services:
  github-runner:
    image: jefriherditriyanto/github-runner:latest
    container_name: github-runner
    restart: unless-stopped
    privileged: true
    environment:
      REPO_URL: https://github.com/username/repo
      RUNNER_TOKEN: YOUR_TOKEN

注意事项

• 基础镜像：基于Alpine的docker:dind
• Runner名称默认设为docker-runner，若同一仓库运行多个容器需注意名称冲突
• 工作目录为_work
• GitHub Actions runner以非root用户runner运行，而dockerd以root运行
• Docker数据存储在/var/lib/docker卷（由Docker自动管理）

安全提示

• 不要在公共仓库中硬编码RUNNER_TOKEN
• 使用密钥管理工具或平台的环境变量注入功能
• GitHub runner token有效期较短，容器重启后若token过期需重新生成
• --privileged参数会赋予容器主机内核的完全访问权限，仅在可信主机上运行此镜像

故障排查

错误：REPO_URL not set / RUNNER_TOKEN not set

• 确保已设置REPO_URL和RUNNER_TOKEN环境变量

错误：Docker daemon failed to start after 30s

• 确认容器以--privileged参数启动
• 查看日志：docker logs github-runner

Runner未在GitHub显示

• 检查REPO_URL格式是否正确（https://github.com/<owner>/<repo>）
• 确认token仍有效（需重新生成则重新生成）
• 查看容器日志：docker logs -f github-runner

镜像标签

• latest：最新构建版本
• <git-sha>：基于特定commit SHA的构建版本