Forgejo Runners

The Forgejo Runner is a daemon that fetches workflows to run from a Forgejo instance, executes them, sends back with the logs and ultimately reports its success or failure.

Please note

For security reasons it is not recommended to install the runner on the same machine as the main Forgejo instance.

---

Setting up a local CI / CD pipeline with Forgejo runners is a great way to control your build system, and if you use a service like Codeberg it reduces their compute cost 👌 good person 👍

Generate token

Navigate through the web UI to your account settings and select Actions -> Runners -> Create new runner copy the registration token and supply it to the docker run commands when registering your new forgejo runner.

Set version number

Use curl and jq to grab the most current runner version and set it as a local variable.

export RUNNER_VERSION=$(curl -X 'GET' https://code.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | jq .name -r | cut -c 2-)

Pull image and register runner

Replace the ${TOKEN} with the generated runner token you just created.

docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:${RUNNER_VERSION} forgejo-runner register --no-interactive --token {TOKEN} --name codeberg_runner --instance https://codeberg.org

Generate config

docker run -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/data --rm code.forgejo.org/forgejo/runner:${RUNNER_VERSION} forgejo-runner generate-config > config.yml

These commands will generate two files in your current directory:

.runner - which is the configuration file produced when registering the runner.

config.yml - which is the main configuration file with defaults in place you can modify to suit your needs and environment.

Docker in Docker

Docker within Docker who would have thought?! Turns out it works really good.

docker-compose.yaml

---
services:
  docker:
    image: docker:dind
    container_name: docker
    privileged: true
    volumes:
      - ./certs:/certs

  forgejo-runner:
    image: code.forgejo.org/forgejo/runner
    container_name: forgejo-runner
    depends_on:
      - docker
    environment:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_TLS_VERIFY: 1
      DOCKER_CERT_PATH: /certs/client
    volumes:
      - ./:/data
      - ./certs:/certs
    expose:
      - "8080"
    command: 'forgejo-runner --config config.yml daemon'
volumes:
  certs: