docs: note forgejo runner perms and token

dir

AGENTS.md

@@ -155,6 +155,13 @@ lib: inputs: self: lib.mkSystem "<os>" ./configuration.nix
 2. Check file extension is `.nix`
 3. Ensure valid Nix syntax
 
+### Forgejo Actions Runner (NixOS)
+1. `DynamicUser` conflicts require `lib.mkForce` if overriding module defaults.
+2. Runner state dir should be `/var/lib/gitea-runner/<instance>`; set `StateDirectory = "gitea-runner"` and let the instance name append.
+3. If the register script fails with `permission denied`, ensure `/var/lib/gitea-runner` exists and is owned by `gitea-runner`.
+4. If workflows need to read a home symlink target, `/home/<user>` must be `0750` (group traverse) and the runner user must be in that group.
+5. A Forgejo deploy token for HTTPS pulls should be stored in agenix and owned by `gitea-runner`; use env-file format (`TOKEN=...`) and read it at runtime.
+
 ### Nushell Warnings
 1. Deprecated `get -i` warning from direnv integration is a short-term workaround in `modules/common/shell/direnv.nix` (custom Nushell hook with `get -o` and HM integration disabled) until upstream home-manager updates.
 

hosts/thegeneralist-central/forgejo/default.nix

@@ -1,3 +1,5 @@
+{ config, lib, pkgs, ... }:
+
 let
   forgejo_root_dir = "/var/lib/forgejo";
   domain = "git.thegeneralist01.com";
@@ -7,6 +9,12 @@ in
 {
   imports = [ ../../../modules/postgresql.nix ];
 
+  age.secrets.forgejoRunnerToken.file = ./forgejo-runner-token.age;
+  age.secrets.forgejoFamilySiteDeployToken.file = ./forgejo-family-site-deploy-token.age;
+  age.secrets.forgejoFamilySiteDeployToken.owner = "gitea-runner";
+  age.secrets.forgejoFamilySiteDeployToken.group = "gitea-runner";
+  age.secrets.forgejoFamilySiteDeployToken.mode = "0400";
+
   services.forgejo = {
     enable = true;
     stateDir = forgejo_folder "state";
@@ -26,6 +34,9 @@ in
         };
 
         attachment.ALLOWED_TYPES = "*/*";
+        actions = {
+          ENABLED = true;
+        };
         cache.ENABLED = true;
 
         "cron.archive_cleanup" =
@@ -90,5 +101,61 @@ in
       };
   };
 
+  services.gitea-actions-runner = {
+    package = pkgs.forgejo-runner;
+    instances.central = {
+      enable = true;
+      name = "thegeneralist-central";
+      url = "https://${domain}";
+      tokenFile = config.age.secrets.forgejoRunnerToken.path;
+      labels = [
+        "native:host"
+        # "node-22:docker://node:22-bookworm"
+        # "nixos-latest:docker://nixos/nix"
+      ];
+
+      # Host-executed jobs need nix + ssh in PATH.
+      hostPackages = with pkgs; [
+        bash
+        coreutils
+        curl
+        gawk
+        gitMinimal
+        gnused
+        nodejs
+        nix
+        openssh
+        wget
+      ];
+    };
+  };
+
+  networking.firewall.trustedInterfaces = [ "br-+" ];
+
+  programs.ssh.knownHosts.central = {
+    hostNames = [ "central" ];
+    publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOkFvw9+AispgqwaYg3ksAZTHJgkCDwFTbWzUh/pVcAS";
+  };
+
+  # Avoid /var/lib/private so the runner can write its state.
+  systemd.services.gitea-runner-central.serviceConfig = {
+    DynamicUser = lib.mkForce false;
+    StateDirectory = lib.mkForce "gitea-runner";
+    StateDirectoryMode = "0755";
+  };
+
+  users.groups.gitea-runner = { };
+  users.users.gitea-runner = {
+    isSystemUser = true;
+    group = "gitea-runner";
+    home = "/var/lib/gitea-runner/central";
+    createHome = true;
+  };
+
+  systemd.tmpfiles.rules = [
+    "d /var/lib/gitea-runner 0755 gitea-runner gitea-runner -"
+    "d /var/lib/gitea-runner/central 0755 gitea-runner gitea-runner -"
+  ];
+
   networking.firewall.allowedTCPPorts = [ 2222 ];
 }

hosts/thegeneralist-central/forgejo/forgejo-family-site-deploy-token.age

@@ -0,0 +1,6 @@
+age-encryption.org/v1
+-> ssh-ed25519 pp9qdQ GJGHfvh/Uxw7ft0YGwY8Opel/kBdmN4SlblkTyEcKjU
+r/WBadLWHFf0U/G/777GeOO37a6wER6sje3xk2pv9Do
+--- 9y4nJZEmjdmJ1ZNOu/8nYadBPDdvXN0sEnNjkx3a9sU
+(h<QG?EE­qáÚþ%<25>­1ÝäôiËŠ
+\!Æ€ÛSÅ76`'—ŸX{fäæ“®Jpû0ëA¥æï88J Œ·ÏÞ7òô]s2·

hosts/thegeneralist-central/forgejo/forgejo-runner-token.age

@@ -0,0 +1,6 @@
+age-encryption.org/v1
+-> ssh-ed25519 pp9qdQ 3zI5p1EPKcJdRWK0ZikK7MEwLON9oX2qRy0Ll8+7rXE
++66HhKgUa3AsYO4gHQmlypR7CgkdaQI7goZCPTHGxEE
+--- R+2xHNQawIBenqYp5t4s7XGDeDLt9cFZXprJSNHe8dE
+74›îA<0X”oexõúVüåÂn²#AÁeàDSã}þb¡§I ¤´Ðh“ÔÇD!`¥QB¿œˆ[û:ˆÛÙúf§$æñÁ™¦—ÏC?2Û“›Möþ
Ô‰ƒNC÷ŸU2¡ÉNuèý
+¸é@&Ç s‚©«÷ؽ‹Ìs…ñ<E280A6>DÉãsdÚÐÞÓ–D¸Xˆ1nØJ

hosts/thegeneralist-central/site.nix

@@ -55,7 +55,7 @@ in
     };
 
     virtualHosts."${family_domain}" = {
-      root = "/var/www/${family_domain}";
+      root = "/var/www/${family_domain}/dist";
       locations."/".tryFiles = "$uri $uri.html $uri/ $uri/index.html =404";
 
       extraConfig = ''

secrets.nix

@@ -10,6 +10,8 @@ in {
   "hosts/thegeneralist-central/credentials_personal.age".publicKeys = [ thegeneralist ];
   "hosts/thegeneralist-central/cache/key.age".publicKeys = [ thegeneralist ];
   "hosts/thegeneralist-central/password.age".publicKeys = [ thegeneralist ];
+  "hosts/thegeneralist-central/forgejo/forgejo-runner-token.age".publicKeys = [ thegeneralist ];
+  "hosts/thegeneralist-central/forgejo/forgejo-family-site-deploy-token.age".publicKeys = [ thegeneralist ];
 
   "modules/linux/tailscale-marshall.age".publicKeys = [ thegeneralist ];
 }