Setting Up a Forgejo Runner With Docker Compose: Registration, Labels and Docker-in-Docker Without Surprises

Nate Holbrook

Nate Holbrook

November 18, 2026

Setting Up a Forgejo Runner With Docker Compose: Registration, Labels and Docker-in-Docker Without Surprises

You have Forgejo running in Docker Compose, the repositories are in, and now you want pushes to run tests and builds. The Actions tab is there, but every workflow sits in a waiting state, because Forgejo itself never executes jobs. That work belongs to a separate program, forgejo-runner, and most of the friction in setting it up comes from three places: how it authenticates to Forgejo, how its labels decide which image a job runs in, and which Docker daemon the job containers end up talking to. This guide walks through each piece in the order you will hit it.

Where forgejo-runner Sits Next to the Forgejo Server

Forgejo stores workflows, queues jobs, keeps logs and artifacts, and shows results in the web UI. The runner is a separate binary that polls Forgejo for pending jobs, starts a container (or a host shell, or an LXC container) for each one, streams the logs back and reports the result. The two only need HTTP connectivity from the runner to Forgejo; Forgejo never connects to the runner. That means the runner can live on the same host, on another machine on your LAN, or on a cheap VPS, as long as it can reach your Forgejo URL.

The official container image is data.forgejo.org/forgejo/runner. The current major version at the time of writing is 13 (the 13.2.x series), and the installation docs reference the tag data.forgejo.org/forgejo/runner:13. Pinning the major tag gets you point releases without surprise breaking changes; pin a full version such as 13.2.1 if you prefer to bump deliberately. Check the runner release notes on code.forgejo.org before moving to a new major, because configuration keys do change between majors.

One thing to accept up front: the Forgejo docs state plainly that the runner performs remote code execution. Anyone who can push a workflow to a repository the runner serves can run code on whatever the runner gives them access to. Keep that in mind when you choose the runner’s scope and how it reaches Docker.

Turning On Actions and Getting a Runner UUID and Token

On current Forgejo releases, the [actions] section of app.ini has ENABLED defaulting to true, so a fresh instance already has Actions switched on. If an older install or an admin turned it off, set it back explicitly:

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://data.forgejo.org

In Compose, the same thing can be set with the environment variable FORGEJO__actions__ENABLED: "true". DEFAULT_ACTIONS_URL controls where short action references such as actions/checkout@v7 are fetched from; the default points at data.forgejo.org, which mirrors the common actions.

Each repository also has to have the Actions unit enabled. In the repository, go to Settings, then Units, then Overview, and make sure the Actions checkbox is ticked. If the checkbox is missing, Actions is disabled at the instance level.

Next, create the runner’s credentials. The current docs recommend creating the runner in the web UI and copying the generated values into the runner’s config file. Pick the scope that matches who should be able to use the runner:

  • Instance-wide (site admin): /admin/actions/runners
  • Organization: /org/{org}/settings/actions/runners
  • Your user account: /user/settings/actions/runners
  • A single repository: /{owner}/{repository}/settings/actions/runners

Click “Create new runner”, give it a name and description, and Forgejo shows a UUID and a token. Treat the token like a password. A narrower scope is the safer default: a repository-scoped runner only picks up jobs from that repository, which limits who can execute code on it.

If you have used older guides, you will have seen forgejo-runner register and forgejo-runner create-runner-file. Both still exist in the 13.x binary, but both are marked deprecated, and the runner logs a warning telling you to declare connections in the runner configuration instead. For automated setups there is also an offline path: generate a 40-character hex secret and run forgejo forgejo-cli actions register --name runner-name --scope myorganization --secret <secret> on the Forgejo host, which prints the UUID. That needs admin access to the Forgejo machine, and the web-UI method is simpler for a single runner.

A robotic arm working over a factory assembly line

A Compose File With a Docker-in-Docker Sidecar

The runner needs a Docker daemon to create job containers. The official Docker installation page uses a docker:dind sidecar rather than the host’s socket, and that is the layout to start with. Adapted from the docs, the compose file looks like this:

services:
  docker-in-docker:
    image: docker:dind
    privileged: true
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: unless-stopped

  runner:
    image: data.forgejo.org/forgejo/runner:13
    depends_on:
      docker-in-docker:
        condition: service_started
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: unless-stopped
    command: forgejo-runner daemon --config runner-config.yml

The docs prepare the data directory before the first start, so the non-root runner user can write to it:

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

Two details matter for safety. The dind daemon listens on TCP 2375 with TLS off and no authentication, so never add a ports: entry for it; it should only be reachable on the compose network. And the dind container runs privileged, which is required for Docker-in-Docker. The trade is still a good one: job containers live inside that daemon, so a workflow that mounts / sees the dind container’s filesystem, not your host’s. The official example in the runner repository goes a step further and enables TLS between runner and dind with a shared certificate volume, which is worth copying if the runner shares a network with other services.

Generating config.yml and Adding the Connection

Generate the default configuration with the same image, then edit it:

docker run --rm data.forgejo.org/forgejo/runner:13 
  forgejo-runner generate-config > data/runner-config.yml

The generated file is long and fully commented. The parts you need to change are the connection, the labels and the container network. The connection goes under server.connections, keyed by a name of your choice:

server:
  connections:
    forgejo:
      url: https://git.example.com/
      uuid: c9e50be9-a7c3-4aee-ba35-624c4ff8c519
      token: paste-the-token-from-the-web-ui

If you would rather keep the token out of the file, the config also accepts token_url pointing at a file, for example file:/data/token.txt. One runner can hold several connections, each with its own labels, which is how a single machine serves both your own instance and a public one such as Codeberg.

Labels: How runs-on Turns Into a Container Image

Labels are the contract between workflows and runners. A workflow’s runs-on value must match a label the runner advertises, and the label tells the runner how to execute the job. The format is <label-name>:<label-type>://<default-image>, where the type is docker, lxc or host:

runner:
  capacity: 1
  labels:
    - docker:docker://data.forgejo.org/oci/node:lts
    - node20:docker://node:20-bookworm
    - ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04

With that list, runs-on: docker starts the job in the Node LTS image from data.forgejo.org, and runs-on: node20 starts it in node:20-bookworm. A job can still override the image with jobs.<job_id>.container. Most actions written for GitHub are JavaScript actions, so whatever image you choose needs Node.js available, which is why Node-based images are the usual default. The ubuntu-latest mapping to a catthehacker image is a common way to make workflows copied from GitHub run with fewer changes, but those images are large.

Avoid the host type unless you fully trust every workflow author. The docs warn that it has no isolation at all and that a single job can permanently damage the host. capacity sets how many jobs run concurrently; leave it at 1 on a small machine and raise it once you know your memory headroom.

Making Job Containers Reach Forgejo

The most common failure after the runner shows as online is a job that starts and then cannot clone the repository. The checkout step fetches from your Forgejo instance’s own URL (the ROOT_URL Forgejo is configured with), and it does so from inside the job container, not from the runner container. If that container cannot resolve or route to that URL, the clone fails.

With the dind layout, the job containers are created inside the dind daemon. The official example sets container.network to host, which puts job containers in the dind container’s network namespace. They then see the compose network the dind container is attached to, so they can reach Forgejo by its service name if Forgejo runs in the same compose project:

container:
  network: host
  privileged: false
  valid_volumes: []
  docker_host: "-"

If Forgejo is behind a reverse proxy with a public hostname, the job container must resolve that hostname too. When ROOT_URL is something like http://localhost:3000, jobs will try to clone from their own localhost and fail; set ROOT_URL to the address users and containers can both reach. Leaving network empty makes the runner create a fresh network per job, which isolates jobs from each other but also from any service names on your compose network.

Metal gears meshing together on a dark workbench

Mounting the Host Docker Socket Instead, and What It Costs

The alternative to dind is to mount /var/run/docker.sock into the runner container and drop DOCKER_HOST. It is simpler and avoids a privileged sidecar, and job images share the host’s image cache. The cost is that the runner, and by extension every workflow, controls the host’s Docker daemon. Access to that socket is effectively root on the host.

It gets more exposed if you also pass the socket into job containers so workflows can run docker build. The container.docker_host setting does this: "-" (the default) shares nothing, automount finds the daemon and mounts it into job containers at /var/run/docker.sock. The docs say this is only advisable when only trusted users can push workflows, and give the example of a step running docker run -v /:/host-mount ubuntu to expose the whole host filesystem. If you need image builds in CI, giving jobs the dind daemon keeps that blast radius inside the sidecar. With the socket approach, also set container.network to the name of the compose network Forgejo is on (for example forgejo_default) so job containers can reach it.

The Actions Cache Server Built Into the Runner

The cache section is enabled by default. When it is on, the runner starts an internal cache server and a cache proxy, and passes an ACTIONS_CACHE_URL to each job so that actions/cache and the caching built into setup actions work. Cached data lives with the runner (under $HOME/.cache/actcache unless you set cache.dir) and is never sent to Forgejo, which is why the data volume should be persistent.

The job containers must be able to reach the runner’s cache proxy. The runner tries to detect a usable address, but the config comments note that detection can fail when job containers sit on a different network from the runner, which is exactly the dind situation. If cache steps time out, set cache.host to an IP or hostname the job containers can reach, such as the runner service’s name on the compose network, and optionally fix proxy_port so it does not change between restarts.

A First Workflow in .forgejo/workflows

Workflows live in .forgejo/workflows/ in the repository. A minimal file such as .forgejo/workflows/test.yaml:

on: [push]

jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v7
      - run: node --version
      - run: npm ci && npm test

Push it, open the Actions tab, and the job should be picked up within a few seconds. The runner polls every fetch_interval (2 seconds by default), so a job that stays queued much longer than that is a label or connection problem, not a slow runner.

Errors You Will Probably See Once

“No matching runner is online” or a job stuck waiting. The runs-on value does not match any label on a runner that can see this repository. Compare it with the labels shown in Settings, Actions, Runners. Also check scope: a runner created under one repository will never pick up jobs from another.

“Cannot connect to the Docker daemon”. In the runner logs, this means DOCKER_HOST is wrong or dind has not finished starting; the runner may need a restart after dind is up. Inside a job, it usually means the step expects Docker but container.docker_host is "-", so no daemon is available to the job.

Checkout fails with a connection or hostname error. The job container cannot reach ROOT_URL. Revisit the network section above: fix ROOT_URL, set container.network, or make the public hostname resolvable from inside the job.

Permission denied writing to /data. The runner runs as a non-root user; the data directory must be owned by the UID in your user: line.

An action cannot be found. Short references resolve against DEFAULT_ACTIONS_URL. If an action exists only on GitHub, use its full URL in uses:.

Once a runner is reliably green, the next steps are usually choosing between Actions and a separate CI system (the comparison of Woodpecker CI and Forgejo Actions covers that trade-off) and automating dependency bumps, which Renovate on Forgejo can run on this same runner. If you are still deciding whether to self-host at all, what a small team gains and gives up versus GitHub is worth reading before you build more on it.

More articles for you