Adding custom runners to Forgejo

hello@mikebell.io (Mike Bell) — Mon, 10 Feb 2025 20:42:52 +0000

This is one of those problems that now that I get it it really shouldn’t have been so hard. Like everything with development and homelabbing documentation is key.

Huge thanks to:

without their toots on Mastodon I wouldn’t have been able to grok and actually get things working.

Now that I have my forgejo instance up and running I’m in the process of migrating all my github repos to my own git forge. As part of the move I needed to setup forgejos runners so that I can run actions on the many private infrastructure repos I have.

Setting up the runners is super simple the forgejo documentation is pretty easy to understand and after following this.

What wasn’t clear was how to add in custom images so that I could tailor the runners how I wanted. My ultimate goal here was to have a runner that had the same functionality I was used to with Github runners. It turns out it’s really simple, if you follow the OCI installation method then you should have a file called .runner this lives in the data directory you defined in your docker-compose.yml.

Your runner file has a section called labels this is where you add the images you want to use. See my example below:

{
"WARNING": "This file is automatically generated by act-runner. Do not edit it manually unless you know what you are doing. Removing this file will cause act runner to re-register as a new runner.",
"id": 1,
"uuid": "",
"name": "remotelab",
"token": "",
"address": "https://code.remotelab.uk",
"labels": [
"docker:docker://node:20-bullseye",
"ubuntu-act-latest:docker://ghcr.io/catthehacker/ubuntu:act-latest"
]
}

When you restart the runner you should see you have the ubuntu-act-latest label available for your actions.

caththehackers images are great but they don’t have the aws cli installed which is a hard requirement for me since I manage a lot of AWS infrastructure with terraform 100% via gitops. To fix this I quickly hacked together a docker file to add in the cli tool:

FROM ghcr.io/catthehacker/ubuntu:act-latest
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
RUN unzip awscliv2.zip && ./aws/install

As a quick and dirty hack I pushed this up manually to forgejo (it fully supports docker images and provides a registry as well!). I can now reference that image inside my .runner file.

You can then reference this in your action:

jobs:
configure-aws:
runs-on: ubuntu-act-latest

I still have a few things to tidy up:

Automate building my custom image
Migrate all repos to forgejo
Migrate to OpenTofu

Thanks for reading via RSS!

Send me a message on Mastodon or email me

Runners on Mike Bell - Blog & Stuff

Adding custom runners to Forgejo