ahoneybun.net/content/posts/forgejo-runners.md

+++ title = "Welcome to Forgejo and it's Runners" date = 2025-12-19 draft = false

[taxonomies] categories = [ "nixos" ] tags = [ "nixos", "nixos-server", "forgejo"] +++

CI (Continuous Integration system)

I have been using some form of a CI either in GitHub or recently GitLab with it's CI but not with Forgejo/Gitea (they both use the same runner process since Forgejo is a hard fork of Gitea) so I thought it was time to change that!

My Forgejo instance

NixOS Service

Getting it going on a NixOS install is pretty easy (without using a secret management tool like agenix):

{ config, pkgs, lib, ... }:

let
  cfg = config.services.forgejo;
  srv = cfg.settings.server;
in
{
  services.forgejo = {
    enable = true;
    database.type = "postgres";
    stateDir = "/mnt/DATA/Git";
    # Enable support for Git Large File Storage
    lfs.enable = true;
    settings = {
      server = {
        DOMAIN = "git.ahoneybun.net";
        # You need to specify this to remove the port from URLs in the web UI.
        ROOT_URL = "https://${srv.DOMAIN}/"; 
        HTTP_PORT = 3001;
      };
      # You can temporarily allow registration to create an admin user.
      service.DISABLE_REGISTRATION = true; 
    };
  };
}

once you add that to your configuration.nix (or another nix file that you import) and rebuild you'll find it running on port 3001 (localhost:3001).

Setting up a Forgejo Runner

Since Forgejo is a fork from Gitea NixOS reuses it's gitea-actions-runner service (you should use something like agenix rather than a plaintext file like I did...):

{ lib, pkgs, config, ... }: {
  services.gitea-actions-runner = {
    package = pkgs.forgejo-runner;
    instances.default = {
      enable = true;
      name = "edi";
      url = "https://git.ahoneybun.net";
       tokenFile = "/etc/nixos/services/forgejo-runner-mono.txt";
      labels = [
        "ubuntu-24.04:docker://ubuntu:24.04"
        "ubuntu-22.04:docker://ubuntu:22.04"
        "nix-latest:docker://nixos/nix:latest"
        "rust-latest:docker://rust:latest"
        "amd64-builder"
      ];
    };
  };
}

I have a few labels which are the docker images I want to use and the name of the runner itself which I'll reference soon.

Now this covers my usage of building on x86_64 but what about aarch64? Well I have my Pi 5 setup with Armbian and after going though armbian-config to install Docker I used this page to set it up as a runner!

aaron@sidera:~$ systemctl status forgejo-runner.service 
● forgejo-runner.service - Forgejo Runner
     Loaded: loaded (/etc/systemd/system/forgejo-runner.service; enabled; preset: enabled)
     Active: active (running) since Mon 2025-12-15 08:30:59 MST; 1 day 3h ago
       Docs: https://forgejo.org/docs/latest/admin/actions/
   Main PID: 91170 (forgejo-runner)
      Tasks: 10 (limit: 4670)
     Memory: 8.8M (peak: 10.8M)
        CPU: 37.373s
     CGroup: /system.slice/forgejo-runner.service
             └─91170 /usr/local/bin/forgejo-runner daemon

Dec 15 12:17:14 sidera forgejo-runner[91170]: time="2025-12-15T12:17:14-07:00" level=info msg="task 139 repo is ahoneybun/lazarus https://data.forgejo.org https://git.ahoneybun.net"
Dec 15 12:17:15 sidera forgejo-runner[91170]: time="2025-12-15T12:17:15-07:00" level=info msg="Cleaning up network for job arm64, and network name is: WORKFLOW-b10a3c6697f9b9e7a59e514dd53d2fef"
Dec 15 12:25:22 sidera forgejo-runner[91170]: time="2025-12-15T12:25:22-07:00" level=info msg="task 142 repo is ahoneybun/lazarus https://data.forgejo.org https://git.ahoneybun.net"
Dec 15 12:25:23 sidera forgejo-runner[91170]: time="2025-12-15T12:25:23-07:00" level=info msg="Cleaning up network for job arm64, and network name is: WORKFLOW-4b01f1d79963a84cfb5f0ae7b7dc2c21"
Dec 15 12:25:52 sidera forgejo-runner[91170]: time="2025-12-15T12:25:52-07:00" level=info msg="task 144 repo is ahoneybun/lazarus https://data.forgejo.org https://git.ahoneybun.net"
Dec 15 12:25:53 sidera forgejo-runner[91170]: time="2025-12-15T12:25:53-07:00" level=info msg="Cleaning up network for job arm64, and network name is: WORKFLOW-1a969f4f5a4f1e8118fcbd787e2bc3e0"
Dec 15 12:27:20 sidera forgejo-runner[91170]: time="2025-12-15T12:27:20-07:00" level=info msg="task 146 repo is ahoneybun/lazarus https://data.forgejo.org https://git.ahoneybun.net"
Dec 15 12:27:21 sidera forgejo-runner[91170]: time="2025-12-15T12:27:21-07:00" level=info msg="Cleaning up network for job arm64, and network name is: WORKFLOW-7d76fbfca6a7d3c3128fa7d75c86b90b"
Dec 15 12:28:20 sidera forgejo-runner[91170]: time="2025-12-15T12:28:20-07:00" level=info msg="task 148 repo is ahoneybun/lazarus https://data.forgejo.org https://git.ahoneybun.net"
Dec 15 12:28:21 sidera forgejo-runner[91170]: time="2025-12-15T12:28:21-07:00" level=info msg="Cleaning up network for job arm64, and network name is: WORKFLOW-826c02b6fed5affadcdb107cdfd65205"

Actions

The version that is in NixOS 25.11 has Actions enabled but the docs say you need to enable it per repository for an older version. Now the interesting part is that Gitea uses GitHub Actions syntax so take this one for example:

name: Example

on:
  push:
    branches: [ main ]

jobs:
  amd64:
    runs-on: [ ubuntu-24.04, amd64-builder ]
    steps:
      - name: System Info
        run: |
          cat /etc/os-release
          echo
          uname -m

here we note that it is using a Ubuntu 24.04 Docker image and it will run on the amd64 system (which is edi in this case), for the Pi 5 I'll say arm64-builder instead.

Other questions

For more reading I have my nix files hosted on GitLab here. Reach out to my on Mastodon for questions!