Configuring Forgejo CI runners

If you are someone selfhosting Forgejo because you want your own git server for private stuff and to be more independent, maybe you want to use the CI. If you want CI, then maybe you also want to commit back sometimes.

In that case, it would be nice to set the username and email for the git user in your CI workloads, right? Doing this is surprisingly hard, but this short article explains how to do it.

Runner

The Forgejo Runner installation guide from the official documentation is good enough to get you going. I’m just going to assume you are familiar with the setup, and maybe with some docker basics.

Git Configuration

We can configure git in 3 ways:

• $HOME/.gitconfig File
• git commands
• Environment variables

Workloads run in docker containers, started by another docker container. We somehow need to get configuration data across two layers of docker. To do this, we must configure the Forgejo runner. We can configure the Forgejo runner with it’s config.yaml file, which we first generate with forgejo-runner generate-config > config.yml as explained in the Forgejo documentation. The fields potentially relevant for us are these:

container:
  # And other options to be used when the container is started (eg, --volume /etc/ssl/certs:/etc/ssl/certs:ro).
  options:
  # Volumes (including bind mounts) can be mounted to containers. Glob syntax is supported, see https://github.com/gobwas/glob
  # You can specify multiple volumes. If the sequence is empty, no volumes can be mounted.
  # For example, if you only allow containers to mount the `data` volume and all the json files in `/src`, you should change the config to:
  # valid_volumes:
  #   - data
  #   - /etc/ssl/certs
  # If you want to allow any volume, please use the following configuration:
  # valid_volumes:
  #   - '**'
  valid_volumes: []

The comments in that file seem a bit inaccurate. I tried to get it working with a volume for over an hour, with many different configurations.

Since getting a volume mount to work over two layers of docker didn’t seem to work for me and we don’t have a way to run commands in the docker containers that are created for each workload, I ended up using environment variables in the options field.

container:
    options: options: -e GIT_AUTHOR_NAME="Forgejo CI" -e GIT_AUTHOR_EMAIL="ci+noreply@cscherr.de"

If you’re wondering, those are command line options for the docker CLI. You can set other config options for git with other environment variables, see man git config.

Additional tips

If you want to try and tinker around with the Forgejo runner configs, it may be useful to set the logging to something more verbose than the default, like job_level: info

If you want multiple runners instead of just one, you can just change the capacity from a default of 1 to something like 3. This way, you can avoid having to define multiple runner-docker-containers yourself!