Forgejo Runner (Docker Compose)

Run Forgejo Runner with Docker Compose, using Docker-in-Docker (dind) so workflows can run jobs in containers.

This setup follows the Forgejo Runner installation guide – OCI image installation.

Overview

• docker-in-docker – docker:dind service that provides a Docker daemon for the runner.
• runner – Forgejo Runner OCI image; connects to dind via DOCKER_HOST and stores config and registration under ./data.

The runner runs as user 1001:1001 (non-root) with ./data mounted for config, .runner, and cache.

Requirements

• Docker and Docker Compose (e.g. docker compose).
• A Forgejo instance and a runner registration token from:
  • Instance: /admin/actions/runners → Create new runner
  • Organization: /org/{org}/settings/actions/runners
  • User: /user/settings/actions/runners
  • Repository: /{owner}/{repo}/settings/actions/runners

Quick start

1. Environment

Copy the example env file and set the runner image version (optional):

cp env.example .env

Edit .env if you want a specific runner version, for example:

FORGEJO_RUNNER_VERSION=12.6.3

If unset, the compose file uses latest.

2. Prepare the data directory

Create data and give ownership to the runner user (UID/GID 1001):

mkdir -p data/.cache
chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache

3. First run: setup only

Start the stack with the runner in “sleep” mode so you can configure and register it:

1. In compose.yml, use the setup command for the runner:

   command: '/bin/sh -c "while : ; do sleep 1 ; done ;"'
   

2. Start and enter the runner container:

   docker compose up -d
   docker exec -it forgejo-runner /bin/sh
   

3. Inside the container, generate config and register:

   cd /data
   forgejo-runner generate-config > config.yml
   # Edit config.yml if needed (labels, cache, etc.)
   forgejo-runner register
   

   When prompted, provide:
   • Forgejo instance URL (e.g. https://code.forgejo.org/)
   • Runner token (from the “Create new runner” dialog)
   • Runner name (optional)
   • Labels (e.g. docker:docker://node:20-bookworm or leave blank for default)
4. Exit the container and stop the stack:

   exit
   docker compose down
   

4. Run the runner daemon

Switch the runner to the daemon command and start again:

1. In compose.yml, set the runner command to:

   command: '/bin/sh -c "sleep 5; forgejo-runner daemon --config config.yml"'
   

2. Start the stack:

   docker compose up -d
   

The sleep 5 gives the dind service time to be ready before the runner starts.

Configuration

• Runner config: data/config.yml (created with forgejo-runner generate-config). See the runner configuration section in the official docs.
• Registration: Stored in data/.runner; do not edit by hand.
• Environment: FORGEJO_RUNNER_VERSION in .env sets the runner image tag (default: latest).

Documentation

• Forgejo Runner installation guide – binary and OCI install, registration, config, cache, and more.