davbfr/forgejo-runner

Forgejo Runner Docker镜像

这是一个运行Forgejo Actions runner的Docker镜像，支持Docker socket访问。该镜像封装了上游forgejo-runner二进制文件，并在容器启动时生成JSON配置文件，可通过环境变量自定义配置（包括使用config__...键进行嵌套配置覆盖）。

核心功能

• 基于上游Forgejo runner二进制文件构建
• 首次启动时自动注册runner
• 将runner状态存储在/data目录
• 使用Docker socket启动基于容器的任务
• 支持通过环境变量进行嵌套JSON配置覆盖

使用场景

适用于Forgejo平台的自动化工作流场景，如代码构建、测试、部署等，尤其适合需要容器化任务执行的团队或个人开发者。

快速启动

yaml
services:
  runner:
    image: davbfr/forgejo-runner:12
    container_name: forgejo-runner
    environment:
      - FORGEJO_INSTANCE_URL=https://forgejo.example.com
      - FORGEJO_RUNNER_REGISTRATION_TOKEN=你的注册令牌
      - FORGEJO_RUNNER_NAME=docker-runner-01
      - config__runner__capacity=2
      - config__runner__timeout=2h
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

启动命令：

bash
docker compose up -d

必需环境变量

• FORGEJO_INSTANCE_URL: 你的Forgejo实例URL
• FORGEJO_RUNNER_REGISTRATION_TOKEN: Forgejo平台提供的runner注册令牌
• FORGEJO_RUNNER_NAME: 在Forgejo UI中显示的runner名称

持久化数据

挂载/data目录可持久化以下内容：

• 生成的配置文件/data/config.json
• runner注册状态文件/data/.runner

若不挂载持久化卷，容器每次启动都会重新注册为新runner。

Docker Socket

挂载主机Docker socket是执行容器化任务的必要条件：

yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

配置覆盖

容器启动时会先生成默认配置，再应用以config__或CONFIG__开头的环境变量。格式规则如下：

text
config__<层级1键>__<层级2键>__<层级3键>=<值>

示例：

text
config__runner__capacity=2
config__cache__enabled=false
config__runner__labels=["ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"]
config__runner__envs__HTTP_PROXY=http://proxy.internal:3128

上述配置会转换为JSON更新：

json
{
  "runner": {
    "capacity": 2,
    "labels": ["ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"],
    "envs": {"HTTP_PROXY": "http://proxy.internal:3128"}
  },
  "cache": {"enabled": false}
}

值解析规则：

• 有效JSON格式的值会被解析为对应类型（布尔、数字、数组等）
• 非JSON格式的值保持为字符串

默认行为

容器启动流程：

1. 写入默认配置/data/config.json
2. 应用所有config__覆盖配置
3. 若/data/.runner不存在则自动注册runner
4. 启动forgejo-runner daemon服务

注意事项

• 注册仅在/data/.runner缺失时执行一次
• 重新注册需删除/data/.runner后重启容器
• runner标签需通过config__runner__labels的JSON数组配置

自定义标签示例

yaml
services:
  runner:
    image: davbfr/forgejo-runner:12
    environment:
      - FORGEJO_INSTANCE_URL=[***]
      - FORGEJO_RUNNER_REGISTRATION_TOKEN=你的注册令牌
      - FORGEJO_RUNNER_NAME=docker-runner-01
      - config__runner__labels=["ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04","docker:docker://data.forgejo.org/oci/node:lts"]
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped