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 a runner registration token or a
45 (fine-grained) personal access token (PAT).
46 The file should contain exactly one line with the token without any newline.
47 If a registration token is given, it can be used to re-register a runner of the same
48 name but is time-limited. If the file contains a PAT, the service creates a new
49 registration token on startup as needed. Make sure the PAT has a scope of
50 `admin:org` for organization-wide registrations or a scope of
51 `repo` for a single repository. Fine-grained PATs need read and write permission
52 to the "Adminstration" resources.
53
54 Changing this option or the file's content triggers a new runner registration.
55 '';
56 example = "/run/secrets/github-runner/nixos.token";
57 };
58
59 name = let
60 # Same pattern as for `networking.hostName`
61 baseType = types.strMatching "^$|^[[:alnum:]]([[:alnum:]_-]{0,61}[[:alnum:]])?$";
62 in mkOption {
63 type = if includeNameDefault then baseType else types.nullOr baseType;
64 description = lib.mdDoc ''
65 Name of the runner to configure. Defaults to the hostname.
66
67 Changing this option triggers a new runner registration.
68 '';
69 example = "nixos";
70 } // (if includeNameDefault then {
71 default = config.networking.hostName;
72 defaultText = literalExpression "config.networking.hostName";
73 } else {
74 default = null;
75 });
76
77 runnerGroup = mkOption {
78 type = types.nullOr types.str;
79 description = lib.mdDoc ''
80 Name of the runner group to add this runner to (defaults to the default runner group).
81
82 Changing this option triggers a new runner registration.
83 '';
84 default = null;
85 };
86
87 extraLabels = mkOption {
88 type = types.listOf types.str;
89 description = lib.mdDoc ''
90 Extra labels in addition to the default (`["self-hosted", "Linux", "X64"]`).
91
92 Changing this option triggers a new runner registration.
93 '';
94 example = literalExpression ''[ "nixos" ]'';
95 default = [ ];
96 };
97
98 replace = mkOption {
99 type = types.bool;
100 description = lib.mdDoc ''
101 Replace any existing runner with the same name.
102
103 Without this flag, registering a new runner with the same name fails.
104 '';
105 default = false;
106 };
107
108 extraPackages = mkOption {
109 type = types.listOf types.package;
110 description = lib.mdDoc ''
111 Extra packages to add to `PATH` of the service to make them available to workflows.
112 '';
113 default = [ ];
114 };
115
116 extraEnvironment = mkOption {
117 type = types.attrs;
118 description = lib.mdDoc ''
119 Extra environment variables to set for the runner, as an attrset.
120 '';
121 example = {
122 GIT_CONFIG = "/path/to/git/config";
123 };
124 default = {};
125 };
126
127 serviceOverrides = mkOption {
128 type = types.attrs;
129 description = lib.mdDoc ''
130 Overrides for the systemd service. Can be used to adjust the sandboxing options.
131 '';
132 example = {
133 ProtectHome = false;
134 };
135 default = {};
136 };
137
138 package = mkOption {
139 type = types.package;
140 description = lib.mdDoc ''
141 Which github-runner derivation to use.
142 '';
143 default = pkgs.github-runner;
144 defaultText = literalExpression "pkgs.github-runner";
145 };
146
147 ephemeral = mkOption {
148 type = types.bool;
149 description = lib.mdDoc ''
150 If enabled, causes the following behavior:
151
152 - Passes the `--ephemeral` flag to the runner configuration script
153 - De-registers and stops the runner with GitHub after it has processed one job
154 - On stop, systemd wipes the runtime directory (this always happens, even without using the ephemeral option)
155 - Restarts the service after its successful exit
156 - On start, wipes the state directory and configures a new runner
157
158 You should only enable this option if `tokenFile` points to a file which contains a
159 personal access token (PAT). If you're using the option with a registration token, restarting the
160 service will fail as soon as the registration token expired.
161 '';
162 default = false;
163 };
164
165 user = mkOption {
166 type = types.nullOr types.str;
167 description = lib.mdDoc ''
168 User under which to run the service. If null, will use a systemd dynamic user.
169 '';
170 default = null;
171 defaultText = literalExpression "username";
172 };
173}