nitra/actions-runner

GitHub Actions Runner Docker 镜像

镜像概述和主要用途

本镜像提供了一个轻量级、可配置的 GitHub Actions 自托管运行器环境。它基于官方 GitHub Actions Runner 应用程序构建，旨在简化自托管运行器的部署和管理流程，使用户能够轻松地在容器化环境中运行 GitHub Actions 工作流。

核心功能和特性

• 基于官方 GitHub Actions Runner 构建，确保与 GitHub 服务的兼容性
• 支持自动更新 runner 应用程序
• 内置多平台支持（x86_64, arm64）
• 可通过环境变量灵活配置
• 支持 Docker-in-Docker (DinD) 模式，允许在工作流中使用 Docker
• 精简的镜像大小，优化启动时间
• 支持非 root 用户运行，增强安全性

使用场景和适用范围

• 需要在私有基础设施上运行 GitHub Actions 工作流的团队
• 需要自定义运行环境的 CI/CD 流程
• 需要在特定操作系统或架构上测试软件的开发团队
• 需要隔离不同项目或团队的 CI/CD 环境
• Kubernetes 或其他容器编排平台中的 CI/CD 节点
• 需要快速扩展或缩减 runner 资源的动态工作负载

使用方法和配置说明

基本使用方法

使用 docker run 命令

bash
docker run -d \
  --name github-runner \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  nitra/actions-runner

使用 Docker Compose

yaml
version: '3.8'

services:
  runner:
    image: nitra/actions-runner
    container_name: github-runner
    environment:
      - GITHUB_REPOSITORY=<owner>/<repo>
      - GITHUB_TOKEN=<your-personal-access-token>
      - RUNNER_NAME=my-docker-runner
      - RUNNER_LABELS=docker,linux,x64
    restart: unless-stopped

支持的环境变量

Docker-in-Docker 模式

要启用 Docker-in-Docker 模式，需要添加相应的挂载和特权设置：

bash
docker run -d \
  --name github-runner-dind \
  --privileged \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  -e DOCKER_ENABLED=true \
  -v /var/lib/docker \
  nitra/actions-runner

组织级 Runner 配置

要注册为组织级 runner，使用 GITHUB_ORGANIZATION 而非 GITHUB_REPOSITORY：

bash
docker run -d \
  --name github-org-runner \
  -e GITHUB_ORGANIZATION=<your-organization> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  nitra/actions-runner

GitHub Enterprise 配置

对于 GitHub Enterprise 实例，指定企业 URL：

bash
docker run -d \
  --name github-enterprise-runner \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  -e GITHUB_ENTERPRISE_URL=https://github.example.com \
  nitra/actions-runner

自定义工作目录

bash
docker run -d \
  --name github-runner-custom-workdir \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  -e RUNNER_WORKDIR=/home/runner/custom-workdir \
  -v /path/on/host:/home/runner/custom-workdir \
  nitra/actions-runner

高级配置

使用持久化存储

为了在容器重启后保留 runner 配置和工作目录数据，可以挂载外部卷：

bash
docker run -d \
  --name github-runner-persistent \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  -v runner-config:/home/runner/.runner \
  -v runner-workdir:/home/runner/_work \
  nitra/actions-runner

自定义用户和权限

bash
docker run -d \
  --name github-runner-custom-user \
  -e GITHUB_REPOSITORY=<owner>/<repo> \
  -e GITHUB_TOKEN=<your-personal-access-token> \
  -e USER_UID=1001 \
  -e USER_GID=1001 \
  nitra/actions-runner

Kubernetes 部署

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-runner
  namespace: ci
spec:
  replicas: 3
  selector:
    matchLabels:
      app: github-runner
  template:
    metadata:
      labels:
        app: github-runner
    spec:
      containers:
      - name: github-runner
        image: nitra/actions-runner
        env:
        - name: GITHUB_ORGANIZATION
          value: "my-organization"
        - name: GITHUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: github-runner-secrets
              key: github-token
        - name: RUNNER_LABELS
          value: "kubernetes,linux,x64"
        volumeMounts:
        - name: runner-workdir
          mountPath: /home/runner/_work
      volumes:
      - name: runner-workdir
        emptyDir: {}

故障排除

常见问题

1. Runner 无法注册：检查 GITHUB_TOKEN 是否具有足够的权限，个人访问令牌需要 repo 范围（对于仓库 runner）或 admin:org 范围（对于组织 runner）。

2. Docker 命令在工作流中失败：确保已启用 DinD 模式并正确配置了特权访问。

3. Runner 连接不稳定：检查网络连接和防火墙设置，确保 runner 可以访问 api.github.com 和相关域名。

4. 权限问题：尝试调整 USER_UID 和 USER_GID 环境变量，确保与挂载卷的权限匹配。

查看日志

bash
docker logs -f github-runner

维护和更新

更新镜像

bash
docker pull nitra/actions-runner
docker stop github-runner
docker rm github-runner
# 重新运行容器，使用上述 docker run 命令

自动更新 Runner

默认情况下，runner 会自动更新。如需禁用自动更新，设置环境变量 UPDATE_RUNNER=false。

安全注意事项

• 确保 GITHUB_TOKEN 安全存储，避免硬编码在配置文件中
• 考虑使用非特权模式运行容器，除非工作流需要特殊权限
• 定期更新镜像以获取安全补丁
• 限制 runner 的网络访问，只允许必要的出站连接
• 对于生产环境，考虑使用只读文件系统和临时存储，减少***面

许可证

本项目基于 MIT 许可证开源。详细信息请参见项目仓库中的 LICENSE 文件。

相关资源

• https://docs.github.com/en/actions/hosting-your-own-runners
• https://github.com/nitra/actions-runner
• https://hub.docker.com/r/nitra/actions-runner