pyrox.dev
1{ config
2, lib
3, pkgs
4
5, cfg ? config.services.github-runner
6, svcName
7
8, systemdDir ? "${svcName}/${cfg.name}"
9 # %t: Runtime directory root (usually /run); see systemd.unit(5)
10, runtimeDir ? "%t/${systemdDir}"
11 # %S: State directory root (usually /var/lib); see systemd.unit(5)
12, stateDir ? "%S/${systemdDir}"
13 # %L: Log directory root (usually /var/log); see systemd.unit(5)
14, logsDir ? "%L/${systemdDir}"
15 # Name of file stored in service state directory
16, currentConfigTokenFilename ? ".current-token"
17
18, ...
19}:
20
21with lib;
22
23{
24 description = "GitHub Actions runner";
25
26 wantedBy = [ "multi-user.target" ];
27 wants = [ "network-online.target" ];
28 after = [ "network.target" "network-online.target" ];
29
30 environment = {
31 HOME = runtimeDir;
32 RUNNER_ROOT = stateDir;
33 } // cfg.extraEnvironment;
34
35 path = (with pkgs; [
36 bash
37 coreutils
38 git
39 gnutar
40 gzip
41 ]) ++ [
42 config.nix.package
43 ] ++ cfg.extraPackages;
44
45 serviceConfig = rec {
46 ExecStart = "${cfg.package}/bin/Runner.Listener run --startuptype service";
47
48 # Does the following, sequentially:
49 # - If the module configuration or the token has changed, purge the state directory,
50 # and create the current and the new token file with the contents of the configured
51 # token. While both files have the same content, only the later is accessible by
52 # the service user.
53 # - Configure the runner using the new token file. When finished, delete it.
54 # - Set up the directory structure by creating the necessary symlinks.
55 ExecStartPre =
56 let
57 # Wrapper script which expects the full path of the state, runtime and logs
58 # directory as arguments. Overrides the respective systemd variables to provide
59 # unambiguous directory names. This becomes relevant, for example, if the
60 # caller overrides any of the StateDirectory=, RuntimeDirectory= or LogDirectory=
61 # to contain more than one directory. This causes systemd to set the respective
62 # environment variables with the path of all of the given directories, separated
63 # by a colon.
64 writeScript = name: lines: pkgs.writeShellScript "${svcName}-${name}.sh" ''
65 set -euo pipefail
66
67 STATE_DIRECTORY="$1"
68 RUNTIME_DIRECTORY="$2"
69 LOGS_DIRECTORY="$3"
70
71 ${lines}
72 '';
73 runnerRegistrationConfig = getAttrs [ "name" "tokenFile" "url" "runnerGroup" "extraLabels" "ephemeral" ] cfg;
74 newConfigPath = builtins.toFile "${svcName}-config.json" (builtins.toJSON runnerRegistrationConfig);
75 currentConfigPath = "$STATE_DIRECTORY/.nixos-current-config.json";
76 newConfigTokenPath= "$STATE_DIRECTORY/.new-token";
77 currentConfigTokenPath = "$STATE_DIRECTORY/${currentConfigTokenFilename}";
78
79 runnerCredFiles = [
80 ".credentials"
81 ".credentials_rsaparams"
82 ".runner"
83 ];
84 unconfigureRunner = writeScript "unconfigure" ''
85 copy_tokens() {
86 # Copy the configured token file to the state dir and allow the service user to read the file
87 install --mode=666 ${escapeShellArg cfg.tokenFile} "${newConfigTokenPath}"
88 # Also copy current file to allow for a diff on the next start
89 install --mode=600 ${escapeShellArg cfg.tokenFile} "${currentConfigTokenPath}"
90 }
91 clean_state() {
92 find "$STATE_DIRECTORY/" -mindepth 1 -delete
93 copy_tokens
94 }
95 diff_config() {
96 changed=0
97 # Check for module config changes
98 [[ -f "${currentConfigPath}" ]] \
99 && ${pkgs.diffutils}/bin/diff -q '${newConfigPath}' "${currentConfigPath}" >/dev/null 2>&1 \
100 || changed=1
101 # Also check the content of the token file
102 [[ -f "${currentConfigTokenPath}" ]] \
103 && ${pkgs.diffutils}/bin/diff -q "${currentConfigTokenPath}" ${escapeShellArg cfg.tokenFile} >/dev/null 2>&1 \
104 || changed=1
105 # If the config has changed, remove old state and copy tokens
106 if [[ "$changed" -eq 1 ]]; then
107 echo "Config has changed, removing old runner state."
108 echo "The old runner will still appear in the GitHub Actions UI." \
109 "You have to remove it manually."
110 clean_state
111 fi
112 }
113 if [[ "${optionalString cfg.ephemeral "1"}" ]]; then
114 # In ephemeral mode, we always want to start with a clean state
115 clean_state
116 elif [[ "$(ls -A "$STATE_DIRECTORY")" ]]; then
117 # There are state files from a previous run; diff them to decide if we need a new registration
118 diff_config
119 else
120 # The state directory is entirely empty which indicates a first start
121 copy_tokens
122 fi '';
123 configureRunner = writeScript "configure" ''
124 if [[ -e "${newConfigTokenPath}" ]]; then
125 echo "Configuring GitHub Actions Runner"
126 args=(
127 --unattended
128 --disableupdate
129 --work "$RUNTIME_DIRECTORY"
130 --url ${escapeShellArg cfg.url}
131 --labels ${escapeShellArg (concatStringsSep "," cfg.extraLabels)}
132 --name ${escapeShellArg cfg.name}
133 ${optionalString cfg.replace "--replace"}
134 ${optionalString (cfg.runnerGroup != null) "--runnergroup ${escapeShellArg cfg.runnerGroup}"}
135 ${optionalString cfg.ephemeral "--ephemeral"}
136 )
137 # If the token file contains a PAT (i.e., it starts with "ghp_" or "github_pat_"), we have to use the --pat option,
138 # if it is not a PAT, we assume it contains a registration token and use the --token option
139 token=$(<"${newConfigTokenPath}")
140 if [[ "$token" =~ ^ghp_* ]] || [[ "$token" =~ ^github_pat_* ]]; then
141 args+=(--pat "$token")
142 else
143 args+=(--token "$token")
144 fi
145 ${cfg.package}/bin/config.sh "''${args[@]}"
146 # Move the automatically created _diag dir to the logs dir
147 mkdir -p "$STATE_DIRECTORY/_diag"
148 cp -r "$STATE_DIRECTORY/_diag/." "$LOGS_DIRECTORY/"
149 rm -rf "$STATE_DIRECTORY/_diag/"
150 # Cleanup token from config
151 rm "${newConfigTokenPath}"
152 # Symlink to new config
153 ln -s '${newConfigPath}' "${currentConfigPath}"
154 fi
155 '';
156 setupRuntimeDir = writeScript "setup-runtime-dirs" ''
157 # Link _diag dir
158 ln -s "$LOGS_DIRECTORY" "$RUNTIME_DIRECTORY/_diag"
159
160 # Link the runner credentials to the runtime dir
161 ln -s "$STATE_DIRECTORY"/{${lib.concatStringsSep "," runnerCredFiles}} "$RUNTIME_DIRECTORY/"
162 '';
163 in
164 map (x: "${x} ${escapeShellArgs [ stateDir runtimeDir logsDir ]}") [
165 "+${unconfigureRunner}" # runs as root
166 configureRunner
167 setupRuntimeDir
168 ];
169
170 # If running in ephemeral mode, restart the service on-exit (i.e., successful de-registration of the runner)
171 # to trigger a fresh registration.
172 Restart = if cfg.ephemeral then "on-success" else "no";
173 # If the runner exits with `ReturnCode.RetryableError = 2`, always restart the service:
174 # https://github.com/actions/runner/blob/40ed7f8/src/Runner.Common/Constants.cs#L146
175 RestartForceExitStatus = [ 2 ];
176
177 # Contains _diag
178 LogsDirectory = [ systemdDir ];
179 # Default RUNNER_ROOT which contains ephemeral Runner data
180 RuntimeDirectory = [ systemdDir ];
181 # Home of persistent runner data, e.g., credentials
182 StateDirectory = [ systemdDir ];
183 StateDirectoryMode = "0700";
184 WorkingDirectory = runtimeDir;
185
186 InaccessiblePaths = [
187 # Token file path given in the configuration, if visible to the service
188 "-${cfg.tokenFile}"
189 # Token file in the state directory
190 "${stateDir}/${currentConfigTokenFilename}"
191 ];
192
193 KillSignal = "SIGINT";
194
195 # Hardening (may overlap with DynamicUser=)
196 # The following options are only for optimizing:
197 # systemd-analyze security github-runner
198 AmbientCapabilities = "";
199 CapabilityBoundingSet = "";
200 # ProtectClock= adds DeviceAllow=char-rtc r
201 DeviceAllow = "";
202 NoNewPrivileges = true;
203 PrivateDevices = true;
204 PrivateMounts = true;
205 PrivateTmp = true;
206 PrivateUsers = true;
207 ProtectClock = true;
208 ProtectControlGroups = true;
209 ProtectHome = true;
210 ProtectHostname = true;
211 ProtectKernelLogs = true;
212 ProtectKernelModules = true;
213 ProtectKernelTunables = true;
214 ProtectSystem = "strict";
215 RemoveIPC = true;
216 RestrictNamespaces = true;
217 RestrictRealtime = true;
218 RestrictSUIDSGID = true;
219 UMask = "0066";
220 ProtectProc = "invisible";
221 SystemCallFilter = [
222 "~@clock"
223 "~@cpu-emulation"
224 "~@module"
225 "~@mount"
226 "~@obsolete"
227 "~@raw-io"
228 "~@reboot"
229 "~capset"
230 "~setdomainname"
231 "~sethostname"
232 ];
233 RestrictAddressFamilies = [ "AF_INET" "AF_INET6" "AF_UNIX" "AF_NETLINK" ];
234
235 # Needs network access
236 PrivateNetwork = false;
237 # Cannot be true due to Node
238 MemoryDenyWriteExecute = false;
239
240 # The more restrictive "pid" option makes `nix` commands in CI emit
241 # "GC Warning: Couldn't read /proc/stat"
242 # You may want to set this to "pid" if not using `nix` commands
243 ProcSubset = "all";
244 # Coverage programs for compiled code such as `cargo-tarpaulin` disable
245 # ASLR (address space layout randomization) which requires the
246 # `personality` syscall
247 # You may want to set this to `true` if not using coverage tooling on
248 # compiled code
249 LockPersonality = false;
250
251 # Note that this has some interactions with the User setting; so you may
252 # want to consult the systemd docs if using both.
253 DynamicUser = true;
254 } // (
255 lib.optionalAttrs (cfg.user != null) { User = cfg.user; }
256 ) // cfg.serviceOverrides;
257}