pyrox.dev
1{ config
2, lib
3, pkgs
4, includeNameDefault
5, ...
6}:
7
8with lib;
9
10{
11 enable = mkOption {
12 default = false;
13 example = true;
14 description = lib.mdDoc ''
15 Whether to enable GitHub Actions runner.
16
17 Note: GitHub recommends using self-hosted runners with private repositories only. Learn more here:
18 [About self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners).
19 '';
20 type = lib.types.bool;
21 };
22
23 url = mkOption {
24 type = types.str;
25 description = lib.mdDoc ''
26 Repository to add the runner to.
27
28 Changing this option triggers a new runner registration.
29
30 IMPORTANT: If your token is org-wide (not per repository), you need to
31 provide a github org link, not a single repository, so do it like this
32 `https://github.com/nixos`, not like this
33 `https://github.com/nixos/nixpkgs`.
34 Otherwise, you are going to get a `404 NotFound`
35 from `POST https://api.github.com/actions/runner-registration`
36 in the configure script.
37 '';
38 example = "https://github.com/nixos/nixpkgs";
39 };
40
41 tokenFile = mkOption {
42 type = types.path;
43 description = lib.mdDoc ''
44 The full path to a file which contains either
45
46 * a fine-grained personal access token (PAT),
47 * a classic PAT
48 * or a runner registration token
49
50 Changing this option or the `tokenFile`’s content triggers a new runner registration.
51
52 We suggest using the fine-grained PATs. A runner registration token is valid
53 only for 1 hour after creation, so the next time the runner configuration changes
54 this will give you hard-to-debug HTTP 404 errors in the configure step.
55
56 The file should contain exactly one line with the token without any newline.
57 (Use `echo -n '…token…' > …token file…` to make sure no newlines sneak in.)
58
59 If the file contains a PAT, the service creates a new registration token
60 on startup as needed.
61 If a registration token is given, it can be used to re-register a runner of the same
62 name but is time-limited as noted above.
63
64 For fine-grained PATs:
65
66 Give it "Read and Write access to organization/repository self hosted runners",
67 depending on whether it is organization wide or per-repository. You might have to
68 experiment a little, fine-grained PATs are a `beta` Github feature and still subject
69 to change; nonetheless they are the best option at the moment.
70
71 For classic PATs:
72
73 Make sure the PAT has a scope of `admin:org` for organization-wide registrations
74 or a scope of `repo` for a single repository.
75
76 For runner registration tokens:
77
78 Nothing special needs to be done, but updating will break after one hour,
79 so these are not recommended.
80 '';
81 example = "/run/secrets/github-runner/nixos.token";
82 };
83
84 name = let
85 # Same pattern as for `networking.hostName`
86 baseType = types.strMatching "^$|^[[:alnum:]]([[:alnum:]_-]{0,61}[[:alnum:]])?$";
87 in mkOption {
88 type = if includeNameDefault then baseType else types.nullOr baseType;
89 description = lib.mdDoc ''
90 Name of the runner to configure. Defaults to the hostname.
91
92 Changing this option triggers a new runner registration.
93 '';
94 example = "nixos";
95 } // (if includeNameDefault then {
96 default = config.networking.hostName;
97 defaultText = literalExpression "config.networking.hostName";
98 } else {
99 default = null;
100 });
101
102 runnerGroup = mkOption {
103 type = types.nullOr types.str;
104 description = lib.mdDoc ''
105 Name of the runner group to add this runner to (defaults to the default runner group).
106
107 Changing this option triggers a new runner registration.
108 '';
109 default = null;
110 };
111
112 extraLabels = mkOption {
113 type = types.listOf types.str;
114 description = lib.mdDoc ''
115 Extra labels in addition to the default (`["self-hosted", "Linux", "X64"]`).
116
117 Changing this option triggers a new runner registration.
118 '';
119 example = literalExpression ''[ "nixos" ]'';
120 default = [ ];
121 };
122
123 replace = mkOption {
124 type = types.bool;
125 description = lib.mdDoc ''
126 Replace any existing runner with the same name.
127
128 Without this flag, registering a new runner with the same name fails.
129 '';
130 default = false;
131 };
132
133 extraPackages = mkOption {
134 type = types.listOf types.package;
135 description = lib.mdDoc ''
136 Extra packages to add to `PATH` of the service to make them available to workflows.
137 '';
138 default = [ ];
139 };
140
141 extraEnvironment = mkOption {
142 type = types.attrs;
143 description = lib.mdDoc ''
144 Extra environment variables to set for the runner, as an attrset.
145 '';
146 example = {
147 GIT_CONFIG = "/path/to/git/config";
148 };
149 default = {};
150 };
151
152 serviceOverrides = mkOption {
153 type = types.attrs;
154 description = lib.mdDoc ''
155 Modify the systemd service. Can be used to, e.g., adjust the sandboxing options.
156 '';
157 example = {
158 ProtectHome = false;
159 RestrictAddressFamilies = [ "AF_PACKET" ];
160 };
161 default = {};
162 };
163
164 package = mkOption {
165 type = types.package;
166 description = lib.mdDoc ''
167 Which github-runner derivation to use.
168 '';
169 default = pkgs.github-runner;
170 defaultText = literalExpression "pkgs.github-runner";
171 };
172
173 ephemeral = mkOption {
174 type = types.bool;
175 description = lib.mdDoc ''
176 If enabled, causes the following behavior:
177
178 - Passes the `--ephemeral` flag to the runner configuration script
179 - De-registers and stops the runner with GitHub after it has processed one job
180 - On stop, systemd wipes the runtime directory (this always happens, even without using the ephemeral option)
181 - Restarts the service after its successful exit
182 - On start, wipes the state directory and configures a new runner
183
184 You should only enable this option if `tokenFile` points to a file which contains a
185 personal access token (PAT). If you're using the option with a registration token, restarting the
186 service will fail as soon as the registration token expired.
187 '';
188 default = false;
189 };
190
191 user = mkOption {
192 type = types.nullOr types.str;
193 description = lib.mdDoc ''
194 User under which to run the service. If null, will use a systemd dynamic user.
195 '';
196 default = null;
197 defaultText = literalExpression "username";
198 };
199
200 workDir = mkOption {
201 type = with types; nullOr str;
202 description = lib.mdDoc ''
203 Working directory, available as `$GITHUB_WORKSPACE` during workflow runs
204 and used as a default for [repository checkouts](https://github.com/actions/checkout).
205 The service cleans this directory on every service start.
206
207 A value of `null` will default to the systemd `RuntimeDirectory`.
208 '';
209 default = null;
210 };
211}