Setting up a Self-Hosted Forgejo Actions Runner with Docker Compose
I created an account on Codeberg the other day with the intention of hosting some of my code there in the future. So far, 100% of my open source activity happens on GitHub, and while they do a lot of things well, this seems like a good time to try alternatives considering the ongoing enshittification of major parts of the web.
I've been aware of Codeberg for a while, and after a friend (hi n0toose!) confirmed that the underlying software (Forgejo, a fork of Gitea) supports disabling pull request for a repository — a feature famously missing on GitHub — I was fully on board.
They optionally provide a hosted instance of Woodpecker CI for projects hosted on Codeberg, but I quickly ran into issues with workflows being slow and more importantly logs not loading, making the conversion from GitHub Actions a rather painful task. The other option is using Forgejo Actions, a relatively new feature building on top of
act for compatibility with existing GitHub Actions workflows. However, Codeberg currently doesn't provide hosted runners for this type of CI, so I looked into hosting my own :^)
Setting up a Forgejo Runner
Installation of the Forgejo Runner is covered in their documentation and doesn't need me writing this post. They only describe running directly on the host and in LXC containers; but since my entire self-hosted software stack runs on Docker Compose this wasn't an option.
Adding the Docker Compose service
Dockerfile is available, so I only had to figure out the configuration. Summarized we need the following:
- I haven't found a pre-built variant of the docker image anywhere, so the first step is cloning the repo (to
src/forgejo-runner/in this case) and adding a service with a
ENTRYPOINTis a plain
/bin/forgejo-runner, so we add the
- A volume mounting
/var/run/docker.sockfrom the host into the container so containers can be spawned for running workflows
In YAML it looks like this:
services: forgejo-runner: build: ./src/forgejo-runner command: "daemon" volumes: - /var/run/docker.sock:/var/run/docker.sock
At this point, we can register the runner with a Forgejo instance, in my case Codeberg. Follow the steps outlined here to obtain a registration token, then run:
docker compose run --rm --entrypoint sh forgejo-runner
…which will drop you into a shell within the container, from where we can invoke the registration:
After completing all prompts, a file
.runner should be created, the contents of which need to be copied to the host so we can mount it as a volume later.
Configuring the Forgejo Runner
Additionally, create a config file for the runner (
config.yml) which will also be mounted as a volume and specified via a command line argument.
All available config options are explained in the docs, and if you're happy with the defaults you can skip this step. However, I'd definitely recommend changing
runner.capacity to something greater than one, and if you want to keep caching enabled we'll need to tweak a few other things. Updated Docker Compose config:
services: forgejo-runner: build: ./src/forgejo-runner command: "daemon --config config.yml" volumes: - /var/run/docker.sock:/var/run/docker.sock - ./volume/.runner:/.runner - ./volume/config.yml:/config.yml
While I'm using bind mounts here, you can of course use any other available method of putting files into the container!
Making Caching Work
One of the hardest problems in computer science, and no exception here. Caching (e.g. for various setup actions and
actions/cache) is enabled by default, but the cache server will not be reachable from within the created workflow containers without intervention. This is because a random port is used by default (
cache.port set to
0), which is not exposed on the runner container. I also had to tweak the
container.network option to use Docker Compose's
docker_default network which the runner container is reachable on.
Change this accordingly if your Docker networking setup is more involved :^)
This is what the
config.yaml file looks like for the above:
cache: enabled: true host: forgejo-runner port: 8080 container: network: docker_default
Additionally, expose port 8080 on the container:
services: forgejo-runner: ... expose: - "8080"
Optionally, you can change the cache directory (
/root/.cache) and/or create a separate volume for it.
Putting It All together
Starting the container should now allow the daemon to run and show up as active on the Forgejo interface:
For me, importing existing workflow files written for GitHub Actions worked seamlessly after making the following changes:
- Moving them to
.forgejo/workflows/(optional but less confusing than keeping
docker(Labels in the screenshot above, not Name!)
ghcr.io/catthehacker/ubuntu:act-22.04. Other images will work as well but might require additional setup steps, this one matches GitHub Actions closely.
uses: https://github.com/goto-bus-stop/setup-zig@v2. This is not needed for actions mirrored on Codeberg, e.g.
Lastly, enable Actions in the repository settings, push some changes, and hope for the best :^)