diff options
Diffstat (limited to 'nixos/modules/services/continuous-integration/github-runner.nix')
-rw-r--r-- | nixos/modules/services/continuous-integration/github-runner.nix | 401 |
1 files changed, 14 insertions, 387 deletions
diff --git a/nixos/modules/services/continuous-integration/github-runner.nix b/nixos/modules/services/continuous-integration/github-runner.nix index 2ece75722a1d3..24d02c931a4ae 100644 --- a/nixos/modules/services/continuous-integration/github-runner.nix +++ b/nixos/modules/services/continuous-integration/github-runner.nix @@ -1,396 +1,23 @@ -{ config, pkgs, lib, ... }: +{ config +, pkgs +, lib +, ... +}@args: + with lib; + let cfg = config.services.github-runner; - svcName = "github-runner"; - systemdDir = "${svcName}/${cfg.name}"; - # %t: Runtime directory root (usually /run); see systemd.unit(5) - runtimeDir = "%t/${systemdDir}"; - # %S: State directory root (usually /var/lib); see systemd.unit(5) - stateDir = "%S/${systemdDir}"; - # %L: Log directory root (usually /var/log); see systemd.unit(5) - logsDir = "%L/${systemdDir}"; - # Name of file stored in service state directory - currentConfigTokenFilename = ".current-token"; in -{ - options.services.github-runner = { - enable = mkOption { - default = false; - example = true; - description = lib.mdDoc '' - Whether to enable GitHub Actions runner. - - Note: GitHub recommends using self-hosted runners with private repositories only. Learn more here: - [About self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners). - ''; - type = lib.types.bool; - }; - - url = mkOption { - type = types.str; - description = lib.mdDoc '' - Repository to add the runner to. - - Changing this option triggers a new runner registration. - - IMPORTANT: If your token is org-wide (not per repository), you need to - provide a github org link, not a single repository, so do it like this - `https://github.com/nixos`, not like this - `https://github.com/nixos/nixpkgs`. - Otherwise, you are going to get a `404 NotFound` - from `POST https://api.github.com/actions/runner-registration` - in the configure script. - ''; - example = "https://github.com/nixos/nixpkgs"; - }; - - tokenFile = mkOption { - type = types.path; - description = lib.mdDoc '' - The full path to a file which contains either a runner registration token or a - personal access token (PAT). - The file should contain exactly one line with the token without any newline. - If a registration token is given, it can be used to re-register a runner of the same - name but is time-limited. If the file contains a PAT, the service creates a new - registration token on startup as needed. Make sure the PAT has a scope of - `admin:org` for organization-wide registrations or a scope of - `repo` for a single repository. - - Changing this option or the file's content triggers a new runner registration. - ''; - example = "/run/secrets/github-runner/nixos.token"; - }; - - name = mkOption { - # Same pattern as for `networking.hostName` - type = types.strMatching "^$|^[[:alnum:]]([[:alnum:]_-]{0,61}[[:alnum:]])?$"; - description = lib.mdDoc '' - Name of the runner to configure. Defaults to the hostname. - - Changing this option triggers a new runner registration. - ''; - example = "nixos"; - default = config.networking.hostName; - defaultText = literalExpression "config.networking.hostName"; - }; - - runnerGroup = mkOption { - type = types.nullOr types.str; - description = lib.mdDoc '' - Name of the runner group to add this runner to (defaults to the default runner group). - - Changing this option triggers a new runner registration. - ''; - default = null; - }; - - extraLabels = mkOption { - type = types.listOf types.str; - description = lib.mdDoc '' - Extra labels in addition to the default (`["self-hosted", "Linux", "X64"]`). - Changing this option triggers a new runner registration. - ''; - example = literalExpression ''[ "nixos" ]''; - default = [ ]; - }; - - replace = mkOption { - type = types.bool; - description = lib.mdDoc '' - Replace any existing runner with the same name. - - Without this flag, registering a new runner with the same name fails. - ''; - default = false; - }; - - extraPackages = mkOption { - type = types.listOf types.package; - description = lib.mdDoc '' - Extra packages to add to `PATH` of the service to make them available to workflows. - ''; - default = [ ]; - }; - - package = mkOption { - type = types.package; - description = lib.mdDoc '' - Which github-runner derivation to use. - ''; - default = pkgs.github-runner; - defaultText = literalExpression "pkgs.github-runner"; - }; - - ephemeral = mkOption { - type = types.bool; - description = lib.mdDoc '' - If enabled, causes the following behavior: - - - Passes the `--ephemeral` flag to the runner configuration script - - De-registers and stops the runner with GitHub after it has processed one job - - On stop, systemd wipes the runtime directory (this always happens, even without using the ephemeral option) - - Restarts the service after its successful exit - - On start, wipes the state directory and configures a new runner - - You should only enable this option if `tokenFile` points to a file which contains a - personal access token (PAT). If you're using the option with a registration token, restarting the - service will fail as soon as the registration token expired. - ''; - default = false; - }; - }; +{ + options.services.github-runner = import ./github-runner/options.nix (args // { + # Users don't need to specify options.services.github-runner.name; it will default + # to the hostname. + includeNameDefault = true; + }); config = mkIf cfg.enable { - warnings = optionals (isStorePath cfg.tokenFile) [ - '' - `services.github-runner.tokenFile` points to the Nix store and, therefore, is world-readable. - Consider using a path outside of the Nix store to keep the token private. - '' - ]; - - systemd.services.${svcName} = { - description = "GitHub Actions runner"; - - wantedBy = [ "multi-user.target" ]; - wants = [ "network-online.target" ]; - after = [ "network.target" "network-online.target" ]; - - environment = { - HOME = runtimeDir; - RUNNER_ROOT = stateDir; - }; - - path = (with pkgs; [ - bash - coreutils - git - gnutar - gzip - ]) ++ [ - config.nix.package - ] ++ cfg.extraPackages; - - serviceConfig = rec { - ExecStart = "${cfg.package}/bin/Runner.Listener run --startuptype service"; - - # Does the following, sequentially: - # - If the module configuration or the token has changed, purge the state directory, - # and create the current and the new token file with the contents of the configured - # token. While both files have the same content, only the later is accessible by - # the service user. - # - Configure the runner using the new token file. When finished, delete it. - # - Set up the directory structure by creating the necessary symlinks. - ExecStartPre = - let - # Wrapper script which expects the full path of the state, runtime and logs - # directory as arguments. Overrides the respective systemd variables to provide - # unambiguous directory names. This becomes relevant, for example, if the - # caller overrides any of the StateDirectory=, RuntimeDirectory= or LogDirectory= - # to contain more than one directory. This causes systemd to set the respective - # environment variables with the path of all of the given directories, separated - # by a colon. - writeScript = name: lines: pkgs.writeShellScript "${svcName}-${name}.sh" '' - set -euo pipefail - - STATE_DIRECTORY="$1" - RUNTIME_DIRECTORY="$2" - LOGS_DIRECTORY="$3" - - ${lines} - ''; - runnerRegistrationConfig = getAttrs [ "name" "tokenFile" "url" "runnerGroup" "extraLabels" "ephemeral" ] cfg; - newConfigPath = builtins.toFile "${svcName}-config.json" (builtins.toJSON runnerRegistrationConfig); - currentConfigPath = "$STATE_DIRECTORY/.nixos-current-config.json"; - newConfigTokenPath= "$STATE_DIRECTORY/.new-token"; - currentConfigTokenPath = "$STATE_DIRECTORY/${currentConfigTokenFilename}"; - - runnerCredFiles = [ - ".credentials" - ".credentials_rsaparams" - ".runner" - ]; - unconfigureRunner = writeScript "unconfigure" '' - copy_tokens() { - # Copy the configured token file to the state dir and allow the service user to read the file - install --mode=666 ${escapeShellArg cfg.tokenFile} "${newConfigTokenPath}" - # Also copy current file to allow for a diff on the next start - install --mode=600 ${escapeShellArg cfg.tokenFile} "${currentConfigTokenPath}" - } - - clean_state() { - find "$STATE_DIRECTORY/" -mindepth 1 -delete - copy_tokens - } - - diff_config() { - changed=0 - - # Check for module config changes - [[ -f "${currentConfigPath}" ]] \ - && ${pkgs.diffutils}/bin/diff -q '${newConfigPath}' "${currentConfigPath}" >/dev/null 2>&1 \ - || changed=1 - - # Also check the content of the token file - [[ -f "${currentConfigTokenPath}" ]] \ - && ${pkgs.diffutils}/bin/diff -q "${currentConfigTokenPath}" ${escapeShellArg cfg.tokenFile} >/dev/null 2>&1 \ - || changed=1 - - # If the config has changed, remove old state and copy tokens - if [[ "$changed" -eq 1 ]]; then - echo "Config has changed, removing old runner state." - echo "The old runner will still appear in the GitHub Actions UI." \ - "You have to remove it manually." - clean_state - fi - } - - if [[ "${optionalString cfg.ephemeral "1"}" ]]; then - # In ephemeral mode, we always want to start with a clean state - clean_state - elif [[ "$(ls -A "$STATE_DIRECTORY")" ]]; then - # There are state files from a previous run; diff them to decide if we need a new registration - diff_config - else - # The state directory is entirely empty which indicates a first start - copy_tokens - fi - ''; - configureRunner = writeScript "configure" '' - if [[ -e "${newConfigTokenPath}" ]]; then - echo "Configuring GitHub Actions Runner" - - args=( - --unattended - --disableupdate - --work "$RUNTIME_DIRECTORY" - --url ${escapeShellArg cfg.url} - --labels ${escapeShellArg (concatStringsSep "," cfg.extraLabels)} - --name ${escapeShellArg cfg.name} - ${optionalString cfg.replace "--replace"} - ${optionalString (cfg.runnerGroup != null) "--runnergroup ${escapeShellArg cfg.runnerGroup}"} - ${optionalString cfg.ephemeral "--ephemeral"} - ) - - # If the token file contains a PAT (i.e., it starts with "ghp_"), we have to use the --pat option, - # if it is not a PAT, we assume it contains a registration token and use the --token option - token=$(<"${newConfigTokenPath}") - if [[ "$token" =~ ^ghp_* ]]; then - args+=(--pat "$token") - else - args+=(--token "$token") - fi - - ${cfg.package}/bin/config.sh "''${args[@]}" - - # Move the automatically created _diag dir to the logs dir - mkdir -p "$STATE_DIRECTORY/_diag" - cp -r "$STATE_DIRECTORY/_diag/." "$LOGS_DIRECTORY/" - rm -rf "$STATE_DIRECTORY/_diag/" - - # Cleanup token from config - rm "${newConfigTokenPath}" - - # Symlink to new config - ln -s '${newConfigPath}' "${currentConfigPath}" - fi - ''; - setupRuntimeDir = writeScript "setup-runtime-dirs" '' - # Link _diag dir - ln -s "$LOGS_DIRECTORY" "$RUNTIME_DIRECTORY/_diag" - - # Link the runner credentials to the runtime dir - ln -s "$STATE_DIRECTORY"/{${lib.concatStringsSep "," runnerCredFiles}} "$RUNTIME_DIRECTORY/" - ''; - in - map (x: "${x} ${escapeShellArgs [ stateDir runtimeDir logsDir ]}") [ - "+${unconfigureRunner}" # runs as root - configureRunner - setupRuntimeDir - ]; - - # If running in ephemeral mode, restart the service on-exit (i.e., successful de-registration of the runner) - # to trigger a fresh registration. - Restart = if cfg.ephemeral then "on-success" else "no"; - - # Contains _diag - LogsDirectory = [ systemdDir ]; - # Default RUNNER_ROOT which contains ephemeral Runner data - RuntimeDirectory = [ systemdDir ]; - # Home of persistent runner data, e.g., credentials - StateDirectory = [ systemdDir ]; - StateDirectoryMode = "0700"; - WorkingDirectory = runtimeDir; - - InaccessiblePaths = [ - # Token file path given in the configuration, if visible to the service - "-${cfg.tokenFile}" - # Token file in the state directory - "${stateDir}/${currentConfigTokenFilename}" - ]; - - # By default, use a dynamically allocated user - DynamicUser = true; - - KillSignal = "SIGINT"; - - # Hardening (may overlap with DynamicUser=) - # The following options are only for optimizing: - # systemd-analyze security github-runner - AmbientCapabilities = ""; - CapabilityBoundingSet = ""; - # ProtectClock= adds DeviceAllow=char-rtc r - DeviceAllow = ""; - NoNewPrivileges = true; - PrivateDevices = true; - PrivateMounts = true; - PrivateTmp = true; - PrivateUsers = true; - ProtectClock = true; - ProtectControlGroups = true; - ProtectHome = true; - ProtectHostname = true; - ProtectKernelLogs = true; - ProtectKernelModules = true; - ProtectKernelTunables = true; - ProtectSystem = "strict"; - RemoveIPC = true; - RestrictNamespaces = true; - RestrictRealtime = true; - RestrictSUIDSGID = true; - UMask = "0066"; - ProtectProc = "invisible"; - SystemCallFilter = [ - "~@clock" - "~@cpu-emulation" - "~@module" - "~@mount" - "~@obsolete" - "~@raw-io" - "~@reboot" - "~capset" - "~setdomainname" - "~sethostname" - ]; - RestrictAddressFamilies = [ "AF_INET" "AF_INET6" "AF_UNIX" "AF_NETLINK" ]; - - # Needs network access - PrivateNetwork = false; - # Cannot be true due to Node - MemoryDenyWriteExecute = false; - - # The more restrictive "pid" option makes `nix` commands in CI emit - # "GC Warning: Couldn't read /proc/stat" - # You may want to set this to "pid" if not using `nix` commands - ProcSubset = "all"; - # Coverage programs for compiled code such as `cargo-tarpaulin` disable - # ASLR (address space layout randomization) which requires the - # `personality` syscall - # You may want to set this to `true` if not using coverage tooling on - # compiled code - LockPersonality = false; - }; - }; + services.github-runners.${cfg.name} = cfg; }; } |