nixos/forgejo.runner: initialize module

[adamcstephens]

I couldn't remember exactly where we left the discussion, and couldn't find the context looking at github/matrix, so I went ahead with an initial implementation. This is based off the gitea-actions-runner, but using a template service and applying maximum hardening. It's possible this is too much hardening and will need to be tuned back, but the basic tests at least are passing.

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

[tebriel]

this is very exciting, I'll attempt to replace my manual implementation with this tonight.

[tebriel]

Ok I've moved my config to this module in https://frodux.dev/Frodux/nixos/pulls/772, it has properly registered, picked up a job, and is working on it. First test with docker as a runner working as expected.

[adamcstephens]

This is looking pretty good to me here in nixpkgs. I still need to test this with my local exec runner to see if the hardening is ok.

[tebriel]

I'm still only running it in docker mode but the update to use LoadCredential is working as expected.

[adamcstephens]

Hmm, we may want to rethink this structure slightly. Runner 12.7.0 added multiple server connections https://forgejo.org/2026-02-monthly-report/#forgejo-runner-v1270

[emilylange]

Hmm, we may want to rethink this structure slightly. Runner 12.7.0 added multiple server connections forgejo.org/2026-02-monthly-report#forgejo-runner-v1270

Yes! This is something I wanted to point out ever since we merged #492254. Unfortunately, I had no time to review this PR here yet. But there are a lot of things we can and should absolutely leverage and do differently.

I am hoping I have some time for this within the next two weeks.

[adamcstephens]

I'd definitely appreciate your feedback @emilylange. I'm not in any hurry so when you get a chance, let me know your thoughts. I'd like to get this in before 26.05 but that's still months away.

[adamcstephens]

Another thing to consider would be adding support for ephemeral runners, similar to services.github-runners..ephemeral . They use systemd to wipe the runner directory and re-register on start. The forgejo-runner does support ephmeral runners too. But I'd need to do some research to make sure this is actually valuable. It does add time for runner cycling in my experience with the github runner.

[adamcstephens]

oops, sorry for the noise. forgot about the multiple connections.

[gepbird]

How can we use these credentials properly?

I've tried this example for the first time, my full config:

{
  services.forgejo.runner.instances.test = {
    enable = true;
    url = "https://git.tchfoo.com";
    labels = [ "native:host" ];
    settings.server.connections.gepbird = {
      uuid = "634c3257-0e5a-4d35-b5bb-8620f1b70212";
      token_url = "file:$WORKER1_TOKEN";
    };
    credentials.WORKER1_TOKEN = "/run/keys/worker1";
  };
}

System log:

forgejo-runner[1849855]: Error: invalid configuration: invalid `server` settings: connection "gepbird" is invalid: invalid `token_url`: cannot read secret "file:$WORKER1_TOKEN": open : no such file or directory

According to this comment in the example config, only $CREDENTIALS_DIRECTORY will be resolved. After modifying this part of the configuration:

{
  services.forgejo.runner.instances.test = {
    settings.server.connections.gepbird.token_url = "file:$CREDENTIALS_DIRECTORY/worker1";
    credentials.CREDENTIALS_DIRECTORY = "/run/keys";
  };
}

It still fails, but the variable is resolved:

forgejo-runner[1867313]: Error: invalid configuration: invalid `server` settings: connection "gepbird" is invalid: invalid `token_url`: cannot read secret "file:/run/credentials/forgejo-runner@test.service/worker1": open /run/credentials/forgejo-runner@test.service/worker1: no such file or directory

This configuration works (if the permissions are broad enough):

{
  services.forgejo.runner.instances.test = {
    settings.server.connections.gepbird.token_url = "file:/run/keys/worker1";
    # no credentials option set
  };
}

[adamcstephens]

CREDENTIALS_DIRECTORY is a built in env var for LoadCredential. You should probably choose a different attr name.

{
  services.forgejo.runner.instances.test = {
    settings.server.connections.gepbird.token_url = "file:$CREDENTIALS_DIRECTORY/my_token"; # my_token needs to match the credential *name*
    credentials.my_token = "/run/keys/my_token";
  };
}

[gepbird]

Thanks! Works well, I think an example for the settings option would help many people :)

[gepbird]

There seems to be a problem with escaping dashes in the service name.

Creating a test instance works well:

$ systemctl list-units | grep forgejo-runner
  forgejo-runner@test.service             loaded active running   Forgejo Actions Runner (test)
  system-forgejo\x2drunner.slice          loaded active active    Slice /system/forgejo-runner

But creating test-test instance makes the service fail:

$ systemctl list-units | grep forgejo-runner
● forgejo-runner@test\x2dtest.service     loaded activating auto-restart Forgejo Actions Runner (test-test)
  system-forgejo\x2drunner.slice          loaded active     active       Slice /system/forgejo-runner
$ systemctl status forgejo-runner@test\x2dtest.service     
○ forgejo-runner@testx2dtest.service - Forgejo Actions Runner (testx2dtest)
     Loaded: bad-setting (Reason: Unit forgejo-runner@testx2dtest.service has a bad unit file setting.)
     Active: inactive (dead)

May 14 21:24:49 geptop-xmg systemd[1]: forgejo-runner@testx2dtest.service: Service has no ExecStart=, ExecStop=, or SuccessAction=. Refusing.

[adamcstephens]

$ systemctl status forgejo-runner@test\x2dtest.service     
○ forgejo-runner@testx2dtest.service - Forgejo Actions Runner (testx2dtest)

It appears your shell may have removed the backslash here?

[gepbird]

It appears your shell may have removed the backslash here?

You're right, here are the correct error logs:

$ systemctl status 'forgejo-runner@test\x2dtest.service'
● forgejo-runner@test\x2dtest.service - Forgejo Actions Runner (test-test)
     Loaded: loaded (/etc/systemd/system/forgejo-runner@.service; enabled; preset: ignored)
    Drop-In: /nix/store/92p4ad7mrdgms6zfkkmaqxzhp5jl1nc1-system-units/forgejo-runner@test\x2dtest.service.d
             └─overrides.conf
     Active: activating (auto-restart) (Result: resources) since Thu 2026-05-14 21:35:06 CEST; 1s ago
 Invocation: ad28e3541489454398b200c28e54d792
         IP: 0B in, 0B out
         IO: 0B read, 0B written
   Mem peak: 0B
        CPU: 0
$ journalctl -eu 'forgejo-runner@test\x2dtest.service' | tail
May 14 21:35:30 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Failed with result 'resources'.
May 14 21:35:30 geptop-xmg systemd[1]: Failed to start Forgejo Actions Runner (test-test).
May 14 21:35:32 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Scheduled restart job, restart counter is at 321.
May 14 21:35:32 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Failed to spawn 'start' task: Invalid argument
May 14 21:35:32 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Failed with result 'resources'.
May 14 21:35:32 geptop-xmg systemd[1]: Failed to start Forgejo Actions Runner (test-test).
May 14 21:35:34 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Scheduled restart job, restart counter is at 322.
May 14 21:35:34 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Failed to spawn 'start' task: Invalid argument
May 14 21:35:34 geptop-xmg systemd[1]: forgejo-runner@test\x2dtest.service: Failed with result 'resources'.
May 14 21:35:34 geptop-xmg systemd[1]: Failed to start Forgejo Actions Runner (test-test).

(I was expecting a "Unit X.service could not be found." error if the service name doesn't exist, but turns out @ services behave differently)

[icewind1991]

It seems required to specify the runner labels under settings.runner.labels, which is unexpected given that the top level labels setting exists.

Looking at the code I expect this is because of switching from registrationTokenFile to settings.server.connections, when the registrationTokenFile is used, the explicit forgejo-runner register step does use the top level labels.

Simply defaulting settings.runner.labels to labels seems to be sufficient.

Works great otherwise

[adamcstephens]

Yes, there are probably some more assertions we should add. There’s really two mutually exclusive ways of configuring, url/registrationTokenFile/labels and server.connections. At a minimum, I think I’ll add one to force users to pick one path or the other.

[tebriel]

Also note: if you use server.connections (and the hard to discover token_url) with the .credentials [thank you for including the loadcredential bit made my life easier] you need to put labels in both the labels and settings.runner.labels otherwise the runner doesn't get access to the docker socket.

[adamcstephens]

you need to put labels in both the labels and settings.runner.labels otherwise the runner doesn't get access to the docker socket.

that sounds like a bug, the labels should get merged for the runner instances logic around this.