Development version

This documentation is for a Forgejo version which is not yet released.

To read the documentation for the released version of Forgejo, navigate to the latest version.

Installation from packaging

NixOS

NixOS 26.05 or earlier

A forgejo-runner package is available for Nix. As NixOS service module services.gitea-actions-runner.* can be used.

If application containers are to be used (Docker or Podman), one of virtualisation.docker.enable or virtualisation.podman.enable must also be set to true.

An example service definition might look like this:

services.gitea-actions-runner = {
  package = pkgs.forgejo-runner;
  instances.my-forgejo-instance = {
    enable = true;
    name = "my-forgejo-runner-01";
    token = "<registration-token>";
    url = "https://code.forgejo.org/";
    labels = [
      "node-22:docker://node:22-bookworm"
      "nixos-latest:docker://nixos/nix"
    ];
    settings = { ... };
  };
};

The runner configuration can be specified in services.gitea-actions-runner.instances.<instance>.settings as per Configuration.

NixOS 26.11 or later/Unstable

On versions newer than 26.05, running the Forgejo runner using the services.gitea-actions-runner.* module is no longer supported. The services.forgejo-runner.* module should be used instead.

An example service definition might look like this:

services.forgejo-runner.instances.my-forgejo-instance = {
  enable = true;
  settings = {
    server.connections.forgejo = {
      url = "https://code.forgejo.org/";
      uuid = "<runner-uuid>";
    };
  };
  secrets.server.connections.forgejo.token_url = "/path/to/token/file";
};

Warning

services.forgejo-runner.instances.<instance>.secrets.server.connections.<connection>.token_url should not be set to a path in the Nix store (e.g. ./token), as this will result in the token being readable by all users on the system. Instead, the token file should either be a regular file outside the Nix store, or, ideally, managed by a secret scheme.

Any non-secret configuration can be specified in services.forgejo-runner.instances.<instance>.settings as per configuration.

Note

The services.forgejo-runner module currently does not support running in ephemeral mode.

Additional configuration

IPv6 support is not enabled by default for docker. The following snippet enables this.

virtualisation.docker = {
  daemon.settings = {
    fixed-cidr-v6 = "fd00::/80";
    ipv6 = true;
  };
};

If you would like to use docker runners in combination with cache actions, be sure to add docker bridge interfaces "br-+" to the firewalls’ trusted interfaces:

networking.firewall.trustedInterfaces = [ "br-+" ];