Improve Nix code and docs

Signed-off-by: magic_rb <richard@brezak.sk>

README.md

@@ -66,16 +66,32 @@ We have the following two roles:
 
 ### Integration with GitHub
 
-To integrate with GitHub:
+#### GitHub App
+
+To integrate with GitHub using app authentication:
+
+1. **GitHub App**: Set up a GitHub app for Buildbot to enable GitHub user
+   authentication on the Buildbot dashboard.
+2. **GitHub App private key**: Get the app private key and app ID from GitHub,
+   configure using the buildbot-nix NixOS module.
+3. **Install App**: Install the for an organization or specific user.
+4. **Refresh GitHub Projects**: Currently buildbot-nix doesn't respond to
+   changes (new repositories or installations) automatically, it is therefore
+   necessary to manually trigger a reload or wait for the next periodic reload.
+
+#### Legacy Token Auth
+
+To integrate with GitHub using legacy token authentication:
 
 1. **GitHub Token**: Obtain a GitHub token with `admin:repo_hook` and `repo`
    permissions. For GitHub organizations, it's advisable to create a separate
    GitHub user for managing repository webhooks.
 
-#### Optional when using GitHub login
+### Optional when using GitHub login
 
 1. **GitHub App**: Set up a GitHub app for Buildbot to enable GitHub user
-   authentication on the Buildbot dashboard.
+   authentication on the Buildbot dashboard. (can be the same as for GitHub App
+   auth)
 2. **OAuth Credentials**: After installing the app, generate OAuth credentials
    and configure them in the buildbot-nix NixOS module. Set the callback url to
    `https://<your-domain>/auth/login`.

examples/master.nix

@@ -22,10 +22,13 @@
       # Github user used as a CI identity
       user = "mic92-buildbot";
       authType.legacy = {
-        enable = true;
         # Github token of the same user
         tokenFile = pkgs.writeText "github-token" "ghp_000000000000000000000000000000000000"; # FIXME: replace this with a secret not stored in the nix store
       };
+      # authType.app = {
+      #   id = "00000000000000000"; # FIXME: replace with App ID obtained from GitHub
+      #   secretKeyFile = pkgs.writeText "app-secret.key" "00000000000000000000"; # FIXME: replace with App secret key obtained from GitHub
+      # };
       # A random secret used to verify incoming webhooks from GitHub
       # buildbot-nix will set up a webhook for each project in the organization
       webhookSecretFile = pkgs.writeText "webhookSecret" "00000000000000000000"; # FIXME: replace this with a secret not stored in the nix store

nix/checks/master.nix

@@ -17,7 +17,6 @@
         admins = [ "Mic92" ];
         github = {
           authType.legacy = {
-            enable = true;
             tokenFile = pkgs.writeText "github-token" "ghp_000000000000000000000000000000000000";
           };
           webhookSecretFile = pkgs.writeText "webhookSecret" "00000000000000000000";

nix/master.nix

@@ -124,29 +124,35 @@ in
           default = cfg.authBackend == "github";
         };
 
-        authType = {
+        authType = lib.mkOption {
-          legacy = {
+          type = lib.types.attrTag {
-            enable = lib.mkEnableOption "";
+            legacy = lib.mkOption {
-            tokenFile = lib.mkOption {
+              description = "GitHub legacy auth backend";
-              type = lib.types.path;
+              type = lib.types.submodule {
-              description = "Github token file";
+                options.tokenFile = lib.mkOption {
-            };
+                  type = lib.types.path;
-          };
+                  description = "Github token file";
-
+                };
-          app = {
+              };
-            enable = lib.mkEnableOption "";
-            id = lib.mkOption {
-              type = lib.types.int;
-              description = ''
-                GitHub app ID.
-              '';
             };
 
-            secretKeyFile = lib.mkOption {
+            app = lib.mkOption {
-              type = lib.types.str;
+              description = "GitHub legacy auth backend";
-              description = ''
+              type = lib.types.submodule {
-                GitHub app secret key file location.
+                options.id = lib.mkOption {
-              '';
+                  type = lib.types.int;
+                  description = ''
+                    GitHub app ID.
+                  '';
+                };
+
+                options.secretKeyFile = lib.mkOption {
+                  type = lib.types.str;
+                  description = ''
+                    GitHub app secret key file location.
+                  '';
+                };
+              };
             };
           };
         };
@@ -311,9 +317,9 @@ in
                   buildbot_user=${builtins.toJSON cfg.github.user},
                   topic=${builtins.toJSON cfg.github.topic},
                   auth_type=${
-                          if cfg.github.authType.legacy.enable then
+                          if cfg.github.authType ? "legacy" then
                             ''AuthTypeLegacy()''
-                          else if cfg.github.authType.app.enable then
+                          else if cfg.github.authType ? "app" then
                             ''
                               AuthTypeApp(
                                 app_id=${toString cfg.github.authType.app.id},
@@ -405,10 +411,10 @@ in
           ++ lib.optionals (cfg.github.enable) ([
             "github-webhook-secret:${cfg.github.webhookSecretFile}"
           ]
-          ++ lib.optionals (cfg.github.authType.legacy.enable) [
+          ++ lib.optionals (cfg.github.authType ? "legacy") [
             "github-token:${cfg.github.authType.legacy.tokenFile}"
           ]
-          ++ lib.optionals (cfg.github.authType.app.enable) [
+          ++ lib.optionals (cfg.github.authType ? "app") [
             "github-app-secret-key:${cfg.github.authType.app.secretKeyFile}"
           ])
           ++ lib.optionals cfg.gitea.enable [