nixpkgs/nixos/modules/services/continuous-integration/github-runner.nix
Vincent Haupert f4af2f267a
nixos/github-runner: init at v2.277.1 (#116775)
* github-runner: init at 2.277.1

* nixos/github-runner: initial version

* nixos/github-runner: add warning if tokenFile in Nix store

* github-runner: don't accept unexpected attrs

* github-runner: formatting nits

* github-runner: add pre and post hooks to checkPhase

* nixos/github-runner: update ExecStartPre= comment

* nixos/github-runner: adapt tokenFile option description

Also note that not only a change to the option value will trigger a
reconfiguration but also modifications to the file's content.

* nixos/github-runner: remove mkDefault for DynamicUser=

* nixos/github-runner: create a parent for systemd dirs

Adds a parent directory "github-runner/" to all of the systemd lifecycle
directories StateDirectory=, RuntimeDirectory= and LogDirectory=.

Doing this has two motivations:

1. Something like this would required if we want to support multiple
   runners configurations. Please note that this is already possible
   using NixOS containers.
2. Having an additional parent directory makes it easier to remap
   any of the directories. Without a parent, systemd is going to
   complain if, for example, the given StateDirectory= is a symlink.

* nixos/github-runner: use specifier to get abs runtime path

* nixos/github-runner: use hostname as default for option `name`

Until now, the runner registration did not set the `--name` argument if
the configuration option was `null`, the default for the option.
According to GitHub's documentation, this instructs the registration
script to use the machine's hostname.

This commit causes the registration to always pass the `--name` argument
to the runner configuration script. The option now defaults to
`networking.hostName` which should be always set on NixOS.

This change becomes necessary as the systemd service name includes the
name of the runner since fcfa809 and, hence, expects it to be set. Thus,
an unset `name` option leads to an error.

* nixos/github-runner: use types.str for `name` option

Forcing a `name` option to comply with a pattern which could also be
used as a hostname is probably not required by GitHub.

* nixos/github-runner: pass dir paths explicitly for ExecStartPre=

* nixos/github-runner: update variable and script naming

* nixos/github-runner: let systemd choose the user/group

User and group naming restrictions are a complex topic [1] that I don't
even want to touch. Let systemd figure out the username and group and
reference it in our scripts through the USER environment variable.

[1] https://systemd.io/USER_NAMES/

* Revert "nixos/github-runner: use types.str for `name` option"

The escaping applied to the subdirectory paths given to StateDirectory=,
RuntimeDirectory= and LogsDirectory= apparently doesn't use the same
strategy that is used to escape unit names (cf. systemd-escape(1)). This
makes it unreasonably hard to construct reliable paths which work for
StateDirectory=/RuntimeDirectory=/LogsDirectory= and ExecStartPre=.

Against this background, I decided to (re-)apply restrictions to the
name a user might give for the GitHub runner. The pattern for
`networking.hostName` seems like a reasonable choice, also as its value
is the default if the `name` option isn't set.

This reverts commit 193ac67ba337990c22126da24a775c497dbc7e7d.

* nixos/github-runner: use types.path for `tokenFile` option

* nixos/github-runner: escape options used as shell arguments

* nixos/github-runner: wait for network-online.target

* github-runner: ignore additional online tests
2021-04-10 10:17:10 +00:00

300 lines
12 KiB
Nix

{ config, pkgs, lib, ... }:
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}";
in
{
options.services.github-runner = {
enable = mkOption {
default = false;
example = true;
description = ''
Whether to enable GitHub Actions runner.
Note: GitHub recommends using self-hosted runners with private repositories only. Learn more here:
<link xlink:href="https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners"
>About self-hosted runners</link>.
'';
type = lib.types.bool;
};
url = mkOption {
type = types.str;
description = ''
Repository to add the runner to.
Changing this option triggers a new runner registration.
'';
example = "https://github.com/nixos/nixpkgs";
};
tokenFile = mkOption {
type = types.path;
description = ''
The full path to a file which contains the runner registration token.
The file should contain exactly one line with the token without any newline.
The token can be used to re-register a runner of the same name but is time-limited.
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 = ''
Name of the runner to configure. Defaults to the hostname.
Changing this option triggers a new runner registration.
'';
example = "nixos";
default = config.networking.hostName;
};
runnerGroup = mkOption {
type = types.nullOr types.str;
description = ''
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 = ''
Extra labels in addition to the default (<literal>["self-hosted", "Linux", "X64"]</literal>).
Changing this option triggers a new runner registration.
'';
example = literalExample ''[ "nixos" ]'';
default = [ ];
};
replace = mkOption {
type = types.bool;
description = ''
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 = ''
Extra packages to add to <literal>PATH</literal> of the service to make them available to workflows.
'';
default = [ ];
};
};
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 = runtimeDir;
};
path = (with pkgs; [
bash
coreutils
git
gnutar
gzip
]) ++ [
config.nix.package
] ++ cfg.extraPackages;
serviceConfig = rec {
ExecStart = "${pkgs.github-runner}/bin/runsvc.sh";
# Does the following, sequentially:
# - Copy the current and the previous `tokenFile` to the $RUNTIME_DIRECTORY
# and make it accessible to the service user to allow for a content
# comparison.
# - If the module configuration or the token has changed, clear the state directory.
# - Configure the runner.
# - Copy the configured `tokenFile` to the $STATE_DIRECTORY and make it
# inaccessible to the service user.
# - 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}
'';
currentConfigPath = "$STATE_DIRECTORY/.nixos-current-config.json";
runnerRegistrationConfig = getAttrs [ "name" "tokenFile" "url" "runnerGroup" "extraLabels" ] cfg;
newConfigPath = builtins.toFile "${svcName}-config.json" (builtins.toJSON runnerRegistrationConfig);
currentConfigTokenFilename = ".current-token";
newConfigTokenFilename = ".new-token";
runnerCredFiles = [
".credentials"
".credentials_rsaparams"
".runner"
];
ownConfigTokens = writeScript "own-config-tokens" ''
# Copy current and new token file to runtime dir and make it accessible to the service user
cp ${escapeShellArg cfg.tokenFile} "$RUNTIME_DIRECTORY/${newConfigTokenFilename}"
chmod 600 "$RUNTIME_DIRECTORY/${newConfigTokenFilename}"
chown "$USER" "$RUNTIME_DIRECTORY/${newConfigTokenFilename}"
if [[ -e "$STATE_DIRECTORY/${currentConfigTokenFilename}" ]]; then
cp "$STATE_DIRECTORY/${currentConfigTokenFilename}" "$RUNTIME_DIRECTORY/${currentConfigTokenFilename}"
chmod 600 "$RUNTIME_DIRECTORY/${currentConfigTokenFilename}"
chown "$USER" "$RUNTIME_DIRECTORY/${currentConfigTokenFilename}"
fi
'';
disownConfigTokens = writeScript "disown-config-tokens" ''
# Make the token inaccessible to the runner service user
chmod 600 "$STATE_DIRECTORY/${currentConfigTokenFilename}"
chown root:root "$STATE_DIRECTORY/${currentConfigTokenFilename}"
'';
unconfigureRunner = writeScript "unconfigure" ''
differs=
# Set `differs = 1` if current and new runner config differ or if `currentConfigPath` does not exist
${pkgs.diffutils}/bin/diff -q '${newConfigPath}' "${currentConfigPath}" >/dev/null 2>&1 || differs=1
# Also trigger a registration if the token content changed
${pkgs.diffutils}/bin/diff -q \
"$RUNTIME_DIRECTORY"/{${currentConfigTokenFilename},${newConfigTokenFilename}} \
>/dev/null 2>&1 || differs=1
if [[ -n "$differs" ]]; 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."
find "$STATE_DIRECTORY/" -mindepth 1 -delete
fi
'';
configureRunner = writeScript "configure" ''
empty=$(ls -A "$STATE_DIRECTORY")
if [[ -z "$empty" ]]; then
echo "Configuring GitHub Actions Runner"
token=$(< "$RUNTIME_DIRECTORY"/${newConfigTokenFilename})
RUNNER_ROOT="$STATE_DIRECTORY" ${pkgs.github-runner}/bin/config.sh \
--unattended \
--work "$RUNTIME_DIRECTORY" \
--url ${escapeShellArg cfg.url} \
--token "$token" \
--labels ${escapeShellArg (concatStringsSep "," cfg.extraLabels)} \
--name ${escapeShellArg cfg.name} \
${optionalString cfg.replace "--replace"} \
${optionalString (cfg.runnerGroup != null) "--runnergroup ${escapeShellArg cfg.runnerGroup}"}
# 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 -f "$RUNTIME_DIRECTORY"/${currentConfigTokenFilename}
mv "$RUNTIME_DIRECTORY"/${newConfigTokenFilename} "$STATE_DIRECTORY/${currentConfigTokenFilename}"
# 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 ]}") [
"+${ownConfigTokens}" # runs as root
unconfigureRunner
configureRunner
"+${disownConfigTokens}" # runs as root
setupRuntimeDir
];
# 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;
# By default, use a dynamically allocated user
DynamicUser = true;
KillMode = "process";
KillSignal = "SIGTERM";
# 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 = "";
LockPersonality = true;
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";
# Needs network access
PrivateNetwork = false;
# Cannot be true due to Node
MemoryDenyWriteExecute = false;
};
};
};
}