1 742bb3a1 2022-10-24 stsp <!DOCTYPE html>
4 742bb3a1 2022-10-24 stsp <meta charset="utf-8"/>
5 742bb3a1 2022-10-24 stsp <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 742bb3a1 2022-10-24 stsp <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 742bb3a1 2022-10-24 stsp <title>GOTD.CONF(5)</title>
9 742bb3a1 2022-10-24 stsp <!-- This is an automatically generated file. Do not edit.
10 742bb3a1 2022-10-24 stsp Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
12 742bb3a1 2022-10-24 stsp Permission to use, copy, modify, and distribute this software for any
13 742bb3a1 2022-10-24 stsp purpose with or without fee is hereby granted, provided that the above
14 742bb3a1 2022-10-24 stsp copyright notice and this permission notice appear in all copies.
16 742bb3a1 2022-10-24 stsp THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 742bb3a1 2022-10-24 stsp WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 742bb3a1 2022-10-24 stsp MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 742bb3a1 2022-10-24 stsp ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 742bb3a1 2022-10-24 stsp WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 742bb3a1 2022-10-24 stsp ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 742bb3a1 2022-10-24 stsp OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 742bb3a1 2022-10-24 stsp <div class="head" role="doc-pageheader" aria-label="Manual header
26 742bb3a1 2022-10-24 stsp line"><span class="head-ltitle">GOTD.CONF(5)</span>
27 742bb3a1 2022-10-24 stsp <span class="head-vol">File Formats Manual</span>
28 742bb3a1 2022-10-24 stsp <span class="head-rtitle">GOTD.CONF(5)</span></div>
29 742bb3a1 2022-10-24 stsp <main class="manual-text">
30 742bb3a1 2022-10-24 stsp <section class="Sh">
31 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 742bb3a1 2022-10-24 stsp <p class="Pp"><code class="Nm">gotd.conf</code> —
33 742bb3a1 2022-10-24 stsp <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
35 742bb3a1 2022-10-24 stsp <section class="Sh">
36 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
37 742bb3a1 2022-10-24 stsp <p class="Pp"><code class="Nm">gotd.conf</code> is the run-time configuration
38 742bb3a1 2022-10-24 stsp file for <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>.</p>
39 742bb3a1 2022-10-24 stsp <p class="Pp">The file format is line-based, with one configuration directive
40 b183145b 2024-08-14 op per line. Comments can be put anywhere in the file using a hash mark
41 b183145b 2024-08-14 op (‘#’), and extend to the end of the current line. Arguments
42 b183145b 2024-08-14 op names not beginning with a letter, digit or underscore, as well as reserved
43 b183145b 2024-08-14 op words (such as <code class="Ic">listen</code>,
44 b183145b 2024-08-14 op <code class="Ic">repository</code> <span class="No">or</span>
45 b183145b 2024-08-14 op <code class="Ic">user</code>), must be quoted. Arguments containing
46 b183145b 2024-08-14 op whitespace should be surrounded by double quotes (").</p>
47 a3016eec 2024-10-22 op <p class="Pp">Macros can be defined that are later expanded in context. Macro
48 a3016eec 2024-10-22 op names must start with a letter, digit, or underscore, and may contain any of
49 a3016eec 2024-10-22 op those characters, but may not be reserved words. Macros are not expanded
50 a3016eec 2024-10-22 op inside quotes. For example:</p>
51 a3016eec 2024-10-22 op <div class="Bd Pp Bd-indent Li">
52 a3016eec 2024-10-22 op <pre>path = "/var/run/gotd.sock"
53 a3016eec 2024-10-22 op listen on $path</pre>
56 742bb3a1 2022-10-24 stsp <section class="Sh">
57 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
58 742bb3a1 2022-10-24 stsp CONFIGURATION</a></h2>
59 742bb3a1 2022-10-24 stsp <p class="Pp">The available global configuration directives are as follows:</p>
60 742bb3a1 2022-10-24 stsp <dl class="Bl-tag">
61 47f19dd5 2023-01-17 stsp <dt id="connection"><a class="permalink" href="#connection"><code class="Ic">connection</code></a>
62 47f19dd5 2023-01-17 stsp <var class="Ar">option</var></dt>
63 47f19dd5 2023-01-17 stsp <dd>Set the specified options and limits for connections to the
64 47f19dd5 2023-01-17 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> unix socket.
65 47f19dd5 2023-01-17 stsp <p class="Pp">The <code class="Ic">connection</code> directive may be
66 47f19dd5 2023-01-17 stsp specified multiple times, and multiple <var class="Ar">option</var>
67 47f19dd5 2023-01-17 stsp arguments may be specified within curly braces:</p>
68 47f19dd5 2023-01-17 stsp <p class="Pp"><code class="Ic">connection</code>
69 47f19dd5 2023-01-17 stsp {<var class="Ar">...</var>}</p>
70 47f19dd5 2023-01-17 stsp <p class="Pp">Each option should only be specified once. If a given option
71 47f19dd5 2023-01-17 stsp is listed multiple times, the last line which sets this option wins.</p>
72 47f19dd5 2023-01-17 stsp <p class="Pp">Valid connection options are:</p>
73 47f19dd5 2023-01-17 stsp <dl class="Bl-tag">
74 47f19dd5 2023-01-17 stsp <dt id="request"><a class="permalink" href="#request"><code class="Ic">request
75 47f19dd5 2023-01-17 stsp timeout</code></a> <var class="Ar">seconds</var></dt>
76 47f19dd5 2023-01-17 stsp <dd>Specify the inactivity timeout for operations between client and
77 47f19dd5 2023-01-17 stsp server. If this timeout is exceeded while a Git protocol request is
78 47f19dd5 2023-01-17 stsp being processed, the request will be aborted and the connection will
79 47f19dd5 2023-01-17 stsp be terminated.
80 47f19dd5 2023-01-17 stsp <p class="Pp">The timeout value may also have a suffix indicating its
81 47f19dd5 2023-01-17 stsp unit of measure. Supported suffixes are:</p>
82 47f19dd5 2023-01-17 stsp <p class="Pp"></p>
83 47f19dd5 2023-01-17 stsp <dl class="Bl-tag Bl-compact">
84 47f19dd5 2023-01-17 stsp <dt><var class="Ar">s</var> <span class="No">or</span>
85 47f19dd5 2023-01-17 stsp <var class="Ar">S</var></dt>
86 47f19dd5 2023-01-17 stsp <dd>seconds</dd>
87 47f19dd5 2023-01-17 stsp <dt><var class="Ar">m</var> <span class="No">or</span>
88 47f19dd5 2023-01-17 stsp <var class="Ar">M</var></dt>
89 47f19dd5 2023-01-17 stsp <dd>minutes</dd>
90 47f19dd5 2023-01-17 stsp <dt><var class="Ar">h</var> <span class="No">or</span>
91 47f19dd5 2023-01-17 stsp <var class="Ar">H</var></dt>
92 47f19dd5 2023-01-17 stsp <dd>hours</dd>
94 47f19dd5 2023-01-17 stsp <p class="Pp">The default timeout is 1h (3600 seconds, one hour). This
95 47f19dd5 2023-01-17 stsp should only be changed if legitimate requests are exceeding the
96 47f19dd5 2023-01-17 stsp default timeout for some reason, such as the server spending an
97 47f19dd5 2023-01-17 stsp extraordinary amount of time generating a pack file.</p>
99 47f19dd5 2023-01-17 stsp <dt id="limit"><a class="permalink" href="#limit"><code class="Ic">limit</code></a>
100 47f19dd5 2023-01-17 stsp <code class="Ic">user</code> <var class="Ar">identity</var>
101 47f19dd5 2023-01-17 stsp <var class="Ar">number</var></dt>
102 47f19dd5 2023-01-17 stsp <dd>Limit the maximum amount of concurrent connections by the user with
103 47f19dd5 2023-01-17 stsp the username <var class="Ar">identity</var> to
104 47f19dd5 2023-01-17 stsp <var class="Ar">number</var>. Numeric user IDs are also accepted.
105 47f19dd5 2023-01-17 stsp <p class="Pp">The default per-user limit is 4. This should only be
106 47f19dd5 2023-01-17 stsp changed if concurrent connections from a given user are expected to
107 47f19dd5 2023-01-17 stsp exceed the default limit, for example if an anonymous user is
108 47f19dd5 2023-01-17 stsp granted read access and many concurrent connections will share this
109 47f19dd5 2023-01-17 stsp anonymous user identity.</p>
113 47f19dd5 2023-01-17 stsp <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
114 47f19dd5 2023-01-17 stsp on</code></a> <var class="Ar">path</var></dt>
115 742bb3a1 2022-10-24 stsp <dd>Set the path to the unix socket which <a class="Xr" aria-label="gotd,
116 742bb3a1 2022-10-24 stsp section 8">gotd(8)</a> should listen on. If not specified, the path
117 742bb3a1 2022-10-24 stsp <span class="Pa">/var/run/gotd.sock</span> will be used.</dd>
118 742bb3a1 2022-10-24 stsp <dt id="user"><a class="permalink" href="#user"><code class="Ic">user</code></a>
119 742bb3a1 2022-10-24 stsp <var class="Ar">user</var></dt>
120 742bb3a1 2022-10-24 stsp <dd>Set the <var class="Ar">user</var> which will run
121 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>. Initially,
122 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> requires root
123 47f19dd5 2023-01-17 stsp privileges in order to create its unix socket. Afterwards,
124 47f19dd5 2023-01-17 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> drops privileges to
125 47f19dd5 2023-01-17 stsp the specified <var class="Ar">user</var>. If not specified, the user _gotd
126 b183145b 2024-08-14 op will be used. Numeric user IDs are also accepted.</dd>
129 742bb3a1 2022-10-24 stsp <section class="Sh">
130 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="REPOSITORY_CONFIGURATION"><a class="permalink" href="#REPOSITORY_CONFIGURATION">REPOSITORY
131 742bb3a1 2022-10-24 stsp CONFIGURATION</a></h2>
132 742bb3a1 2022-10-24 stsp <p class="Pp">At least one repository context must exist for
133 47f19dd5 2023-01-17 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> to function. For each
134 47f19dd5 2023-01-17 stsp repository, access rules must be configured using the
135 47f19dd5 2023-01-17 stsp <code class="Ic">permit</code> and <code class="Ic">deny</code>
136 47f19dd5 2023-01-17 stsp configuration directives. Multiple access rules can be specified, and the
137 47f19dd5 2023-01-17 stsp last matching rule determines the action taken. If no rule matches, access
138 47f19dd5 2023-01-17 stsp to the repository is denied.</p>
139 742bb3a1 2022-10-24 stsp <p class="Pp">A repository context is declared with a unique
140 742bb3a1 2022-10-24 stsp <var class="Ar">name</var>, followed by repository-specific configuration
141 742bb3a1 2022-10-24 stsp directives inside curly braces:</p>
142 742bb3a1 2022-10-24 stsp <p class="Pp"><code class="Ic">repository</code> <var class="Ar">name</var>
144 742bb3a1 2022-10-24 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a> and
145 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="git, section 1">git(1)</a> clients can connect to
146 742bb3a1 2022-10-24 stsp a repository by including the repository's unique <var class="Ar">name</var>
147 742bb3a1 2022-10-24 stsp in the request URL. Clients appending the string “.git” to the
148 742bb3a1 2022-10-24 stsp <var class="Ar">name</var> will also be accepted.</p>
149 742bb3a1 2022-10-24 stsp <p class="Pp">If desired, the <var class="Ar">name</var> may contain
150 742bb3a1 2022-10-24 stsp path-separators, “/”, to expose repositories as part of a
151 742bb3a1 2022-10-24 stsp virtual client-visible directory hierarchy.</p>
152 742bb3a1 2022-10-24 stsp <p class="Pp">The available repository configuration directives are as
153 742bb3a1 2022-10-24 stsp follows:</p>
154 742bb3a1 2022-10-24 stsp <dl class="Bl-tag">
155 47f19dd5 2023-01-17 stsp <dt id="deny"><a class="permalink" href="#deny"><code class="Ic">deny</code></a>
156 47f19dd5 2023-01-17 stsp <var class="Ar">identity</var></dt>
157 47f19dd5 2023-01-17 stsp <dd>Deny repository access to users with the username
158 47f19dd5 2023-01-17 stsp <var class="Ar">identity</var>. Group names may be matched by prepending a
159 47f19dd5 2023-01-17 stsp colon (‘:’) to <var class="Ar">identity</var>. Numeric IDs
160 47f19dd5 2023-01-17 stsp are also accepted.</dd>
161 742bb3a1 2022-10-24 stsp <dt id="path"><a class="permalink" href="#path"><code class="Ic">path</code></a>
162 742bb3a1 2022-10-24 stsp <var class="Ar">path</var></dt>
163 47f19dd5 2023-01-17 stsp <dd>Set the path to the Git repository. Must be specified.</dd>
164 47f19dd5 2023-01-17 stsp <dt id="permit"><a class="permalink" href="#permit"><code class="Ic">permit</code></a>
165 47f19dd5 2023-01-17 stsp <var class="Ar">mode</var> <var class="Ar">identity</var></dt>
166 47f19dd5 2023-01-17 stsp <dd>Permit repository access to users with the username
167 47f19dd5 2023-01-17 stsp <var class="Ar">identity</var>. The <var class="Ar">mode</var> argument
168 47f19dd5 2023-01-17 stsp must be set to either <code class="Ic">ro</code> for read-only access, or
169 47f19dd5 2023-01-17 stsp <code class="Ic">rw</code> for read-write access. Group names may be
170 47f19dd5 2023-01-17 stsp matched by prepending a colon (‘:’) to
171 47f19dd5 2023-01-17 stsp <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
172 e68eaba8 2023-04-20 stsp <dt id="protect"><a class="permalink" href="#protect"><code class="Ic">protect</code></a>
173 e68eaba8 2023-04-20 stsp {<var class="Ar">...</var>}</dt>
174 e68eaba8 2023-04-20 stsp <dd>The <code class="Cm">protect</code> directive may be used to protect
175 e68eaba8 2023-04-20 stsp branches and tags in a repository from being overwritten by potentially
176 e68eaba8 2023-04-20 stsp destructive client-side commands, such as when <code class="Cm">got send
177 e68eaba8 2023-04-20 stsp -f</code> and <code class="Cm">git push -f</code> are used to change the
178 e68eaba8 2023-04-20 stsp history of a branch.
179 e68eaba8 2023-04-20 stsp <p class="Pp">To build a set of protected branches and tags, multiple
180 e68eaba8 2023-04-20 stsp <code class="Ic">protect</code> directives may be specified per
181 e68eaba8 2023-04-20 stsp repository and multiple <code class="Ic">protect</code> directive
182 e68eaba8 2023-04-20 stsp parameters may be specified within curly braces.</p>
183 e68eaba8 2023-04-20 stsp <p class="Pp">The available <code class="Cm">protect</code> parameters are
184 e68eaba8 2023-04-20 stsp as follows:</p>
185 e68eaba8 2023-04-20 stsp <dl class="Bl-tag">
186 e68eaba8 2023-04-20 stsp <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
187 e68eaba8 2023-04-20 stsp <var class="Ar">name</var></dt>
188 e68eaba8 2023-04-20 stsp <dd>Protect the named branch. The branch may be created if it does not
189 e68eaba8 2023-04-20 stsp exist yet. Attempts to delete the branch or change its history will be
191 e68eaba8 2023-04-20 stsp <p class="Pp">If the <var class="Ar">name</var> does not already begin
192 e68eaba8 2023-04-20 stsp with “refs/heads/” it will be looked up in the
193 e68eaba8 2023-04-20 stsp “refs/heads/” reference namespace.</p>
195 e68eaba8 2023-04-20 stsp <dt id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
196 e68eaba8 2023-04-20 stsp <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
197 e68eaba8 2023-04-20 stsp <dd>Protect the given reference namespace, assuming that references in
198 e68eaba8 2023-04-20 stsp this namespace represent branches. New branches may be created in the
199 e68eaba8 2023-04-20 stsp namespace. Attempts to change the history of branches or delete them
200 e68eaba8 2023-04-20 stsp will be denied.
201 e68eaba8 2023-04-20 stsp <p class="Pp">The <var class="Ar">namespace</var> argument must be
202 e68eaba8 2023-04-20 stsp absolute, starting with “refs/”.</p>
204 e68eaba8 2023-04-20 stsp <dt id="tag"><a class="permalink" href="#tag"><code class="Ic">tag</code></a>
205 e68eaba8 2023-04-20 stsp <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
206 e68eaba8 2023-04-20 stsp <dd>Protect the given reference namespace, assuming that references in
207 e68eaba8 2023-04-20 stsp this namespace represent tags. New tags may be created in the
208 e68eaba8 2023-04-20 stsp namespace. Attempts to change or delete existing tags will be denied.
209 e68eaba8 2023-04-20 stsp <p class="Pp">The <var class="Ar">namespace</var> argument must be
210 e68eaba8 2023-04-20 stsp absolute, starting with “refs/”.</p>
213 e68eaba8 2023-04-20 stsp <p class="Pp">The special reference namespaces “refs/got/” and
214 e68eaba8 2023-04-20 stsp “refs/remotes/” do not need to be listed in
215 e68eaba8 2023-04-20 stsp <code class="Nm">gotd.conf</code>. These namespaces are always protected
216 e68eaba8 2023-04-20 stsp and even attempts to create new references in these namespaces will
217 e68eaba8 2023-04-20 stsp always be denied.</p>
219 bd0bf387 2024-04-23 stsp <dt id="notify"><a class="permalink" href="#notify"><code class="Ic">notify</code></a>
220 bd0bf387 2024-04-23 stsp {<var class="Ar">...</var>}</dt>
221 bd0bf387 2024-04-23 stsp <dd>The <code class="Ic">notify</code> directive enables notifications about
222 bd0bf387 2024-04-23 stsp new commits or tags added to the repository.
223 bd0bf387 2024-04-23 stsp <p class="Pp">Notifications via email require an SMTP daemon which accepts
224 bd0bf387 2024-04-23 stsp mail for forwarding without requiring client authentication or
225 bd0bf387 2024-04-23 stsp encryption. On <span class="Ux">OpenBSD</span> the
226 bd0bf387 2024-04-23 stsp <a class="Xr" aria-label="smtpd, section 8">smtpd(8)</a> daemon can be
227 bd0bf387 2024-04-23 stsp used for this purpose. The default content of email notifications looks
228 bd0bf387 2024-04-23 stsp similar to the output of the <code class="Cm">got log -d</code>
229 bd0bf387 2024-04-23 stsp command.</p>
230 bd0bf387 2024-04-23 stsp <p class="Pp">Notifications via HTTP require a HTTP or HTTPS server which is
231 bd0bf387 2024-04-23 stsp accepting POST requests with or without HTTP Basic authentication.
232 bd0bf387 2024-04-23 stsp Depending on the use case a custom server-side CGI script may be
233 bd0bf387 2024-04-23 stsp required for the processing of notifications. HTTP notifications can
234 bd0bf387 2024-04-23 stsp achieve functionality similar to Git's server-side post-receive hook
235 bd0bf387 2024-04-23 stsp script with <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> by
236 bd0bf387 2024-04-23 stsp triggering arbitrary post-commit actions via the HTTP server.</p>
237 bd0bf387 2024-04-23 stsp <p class="Pp">The <code class="Ic">notify</code> directive expects
238 bd0bf387 2024-04-23 stsp parameters which must be enclosed in curly braces. The available
239 bd0bf387 2024-04-23 stsp parameters are as follows:</p>
240 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
241 bd0bf387 2024-04-23 stsp <dt id="branch~3"><a class="permalink" href="#branch~3"><code class="Ic">branch</code></a>
242 bd0bf387 2024-04-23 stsp <var class="Ar">name</var></dt>
243 bd0bf387 2024-04-23 stsp <dd>Send notifications about commits to the named branch. The
244 bd0bf387 2024-04-23 stsp <var class="Ar">name</var> will be looked up in the
245 bd0bf387 2024-04-23 stsp “refs/heads/” reference namespace. This directive may be
246 bd0bf387 2024-04-23 stsp specified multiple times to build a list of branches to send
247 bd0bf387 2024-04-23 stsp notifications for. If neither a <code class="Ic">branch</code> nor a
248 bd0bf387 2024-04-23 stsp <code class="Ic">reference namespace</code> are specified then changes
249 bd0bf387 2024-04-23 stsp to any reference will trigger notifications.</dd>
250 bd0bf387 2024-04-23 stsp <dt id="reference"><a class="permalink" href="#reference"><code class="Ic">reference</code></a>
251 bd0bf387 2024-04-23 stsp <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
252 bd0bf387 2024-04-23 stsp <dd>Send notifications about commits or tags within a reference namespace.
253 bd0bf387 2024-04-23 stsp This directive may be specified multiple times to build a list of
254 bd0bf387 2024-04-23 stsp namespaces to send notifications for. If neither a
255 bd0bf387 2024-04-23 stsp <code class="Ic">branch</code> nor a <code class="Ic">reference
256 bd0bf387 2024-04-23 stsp namespace</code> are specified then changes to any reference will
257 bd0bf387 2024-04-23 stsp trigger notifications.</dd>
258 bd0bf387 2024-04-23 stsp <dt id="email"><a class="permalink" href="#email"><code class="Ic">email</code></a>
259 bd0bf387 2024-04-23 stsp [<code class="Ic">from</code> <var class="Ar">sender</var>]
260 bd0bf387 2024-04-23 stsp <code class="Ic">to</code> <var class="Ar">recipient</var>
261 bd0bf387 2024-04-23 stsp [<code class="Ic">reply to</code> <var class="Ar">responder</var>]
262 bd0bf387 2024-04-23 stsp [<code class="Ic">relay</code> <var class="Ar">hostname</var>
263 bd0bf387 2024-04-23 stsp [<code class="Ic">port</code> <var class="Ar">port</var>]]</dt>
264 bd0bf387 2024-04-23 stsp <dd>Send notifications via email to the specified
265 bd0bf387 2024-04-23 stsp <var class="Ar">recipient</var>. This directive may be specified
266 bd0bf387 2024-04-23 stsp multiple times to build a list of recipients to send notifications to.
267 bd0bf387 2024-04-23 stsp <p class="Pp">The <var class="Ar">recipient</var> must be an email
268 bd0bf387 2024-04-23 stsp addresses that accepts mail. The <var class="Ar">sender</var> will
269 bd0bf387 2024-04-23 stsp be used as the From address. If not specified, the sender defaults
270 bd0bf387 2024-04-23 stsp to an email address composed of the user account running
271 bd0bf387 2024-04-23 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> and the local
272 bd0bf387 2024-04-23 stsp hostname.</p>
273 bd0bf387 2024-04-23 stsp <p class="Pp">If a <var class="Ar">responder</var> is specified via the
274 bd0bf387 2024-04-23 stsp <code class="Ic">reply to</code> directive, the
275 bd0bf387 2024-04-23 stsp <var class="Ar">responder</var> will be used as the Reply-to
276 bd0bf387 2024-04-23 stsp address. Setting the Reply-to header can be useful if replies should
277 bd0bf387 2024-04-23 stsp go to a mailing list instead of the <var class="Ar">sender</var>,
278 bd0bf387 2024-04-23 stsp for example.</p>
279 bd0bf387 2024-04-23 stsp <p class="Pp">By default, mail will be sent to the SMTP server listening
280 bd0bf387 2024-04-23 stsp on the loopback address 127.0.0.1 on port 25. The
281 bd0bf387 2024-04-23 stsp <code class="Ic">relay</code> and <code class="Ic">port</code>
282 bd0bf387 2024-04-23 stsp directives can be used to specify a different SMTP server address
283 bd0bf387 2024-04-23 stsp and port.</p>
285 bd0bf387 2024-04-23 stsp <dt id="url"><a class="permalink" href="#url"><code class="Ic">url</code></a>
286 7196cfe5 2024-09-09 stsp <var class="Ar">URL</var> [<code class="Ic">auth</code>
287 7196cfe5 2024-09-09 stsp <var class="Ar">label</var> [<code class="Ic">insecure</code>]]
288 7196cfe5 2024-09-09 stsp [<code class="Ic">hmac</code> <var class="Ar">label</var>]</dt>
289 bd0bf387 2024-04-23 stsp <dd>Send notifications via HTTP. This directive may be specified multiple
290 bd0bf387 2024-04-23 stsp times to build a list of HTTP servers to send notifications to.
291 bd0bf387 2024-04-23 stsp <p class="Pp">The notification will be sent as a POST request to the
292 bd0bf387 2024-04-23 stsp given <var class="Ar">URL</var>, which must be a valid HTTP URL and
293 bd0bf387 2024-04-23 stsp begin with either “http://” or
294 bd0bf387 2024-04-23 stsp “https://”. If HTTPS is used, sending of notifications
295 bd0bf387 2024-04-23 stsp will only succeed if no TLS errors occur.</p>
296 7196cfe5 2024-09-09 stsp <p class="Pp">The optional <code class="Ic">auth</code> directive
297 7196cfe5 2024-09-09 stsp enables HTTP Basic authentication. Authentication credentials must
298 7196cfe5 2024-09-09 stsp be specified in the separate
299 7196cfe5 2024-09-09 stsp <a class="Xr" aria-label="gotd-secrets.conf, section
300 7196cfe5 2024-09-09 stsp 5">gotd-secrets.conf(5)</a> file, using the
301 7196cfe5 2024-09-09 stsp <var class="Ar">label</var> as identifier. Unless the
302 7196cfe5 2024-09-09 stsp <code class="Ic">insecure</code> option is specified the
303 bd0bf387 2024-04-23 stsp notification target <var class="Ar">URL</var> must be a
304 bd0bf387 2024-04-23 stsp “https://” URL to avoid leaking of authentication
305 bd0bf387 2024-04-23 stsp credentials.</p>
306 7196cfe5 2024-09-09 stsp <p class="Pp">If a <code class="Ic">hmac</code> secret is provided, the
307 7196cfe5 2024-09-09 stsp request body will be signed using HMAC, allowing the receiver to
308 7196cfe5 2024-09-09 stsp verify the notification message's authenticity and integrity. The
309 7196cfe5 2024-09-09 stsp HMAC secret to use must be specified in the separate
310 7196cfe5 2024-09-09 stsp <a class="Xr" aria-label="gotd-secrets.conf, section
311 7196cfe5 2024-09-09 stsp 5">gotd-secrets.conf(5)</a> file, using the
312 7196cfe5 2024-09-09 stsp <var class="Ar">label</var> as identifier. The signature uses
313 7196cfe5 2024-09-09 stsp HMAC-SHA256 and will be sent in the HTTP header
314 7196cfe5 2024-09-09 stsp “X-Gotd-Signature”.</p>
315 bd0bf387 2024-04-23 stsp <p class="Pp">The request body contains a JSON object with a
316 bd0bf387 2024-04-23 stsp “notifications” property containing an array of
317 dfc34448 2024-05-06 stsp notification objects. The following notification object properties
318 dfc34448 2024-05-06 stsp are always present:</p>
319 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
320 dfc34448 2024-05-06 stsp <dt id="repo"><a class="permalink" href="#repo"><code class="Dv">repo</code></a></dt>
321 dfc34448 2024-05-06 stsp <dd>The repository name as a string.</dd>
322 dfc34448 2024-05-06 stsp <dt id="authenticated_user"><a class="permalink" href="#authenticated_user"><code class="Dv">authenticated_user</code></a></dt>
323 dfc34448 2024-05-06 stsp <dd>The committer's user account as authenticated by
324 dfc34448 2024-05-06 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> as a
325 dfc34448 2024-05-06 stsp string.</dd>
326 dfc34448 2024-05-06 stsp <dt id="type"><a class="permalink" href="#type"><code class="Dv">type</code></a></dt>
327 dfc34448 2024-05-06 stsp <dd>The notification object type as a string.</dd>
329 dfc34448 2024-05-06 stsp <p class="Pp">Each notification object carries additional type-specific
330 dfc34448 2024-05-06 stsp properties. The types and their type-specific properties are:</p>
331 dfc34448 2024-05-06 stsp <dl class="Bl-tag">
332 bd0bf387 2024-04-23 stsp <dt id="commit"><a class="permalink" href="#commit"><code class="Dv">commit</code></a></dt>
333 bd0bf387 2024-04-23 stsp <dd>The commit notification object has the following fields. Except
334 bd0bf387 2024-04-23 stsp where noted, all are optional.
335 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
336 bd0bf387 2024-04-23 stsp <dt id="short"><a class="permalink" href="#short"><code class="Dv">short</code></a></dt>
337 bd0bf387 2024-04-23 stsp <dd>Boolean, indicates whether the object has all the fields set.
338 bd0bf387 2024-04-23 stsp When several commits are batched in a single send operation,
339 bd0bf387 2024-04-23 stsp not all of the fields are available for each commit
340 bd0bf387 2024-04-23 stsp object.</dd>
341 bd0bf387 2024-04-23 stsp <dt id="id"><a class="permalink" href="#id"><code class="Dv">id</code></a></dt>
342 bd0bf387 2024-04-23 stsp <dd>The commit ID as string, may be abbreviated.</dd>
343 bd0bf387 2024-04-23 stsp <dt id="committer"><a class="permalink" href="#committer"><code class="Dv">committer</code></a></dt>
344 bd0bf387 2024-04-23 stsp <dd>An object with the committer information with the following
346 bd0bf387 2024-04-23 stsp <p class="Pp"></p>
347 bd0bf387 2024-04-23 stsp <dl class="Bl-tag Bl-compact">
348 bd0bf387 2024-04-23 stsp <dt id="full"><a class="permalink" href="#full"><code class="Dv">full</code></a></dt>
349 bd0bf387 2024-04-23 stsp <dd>Committer's full name.</dd>
350 bd0bf387 2024-04-23 stsp <dt id="name"><a class="permalink" href="#name"><code class="Dv">name</code></a></dt>
351 bd0bf387 2024-04-23 stsp <dd>Committer's name.</dd>
352 bd0bf387 2024-04-23 stsp <dt id="mail"><a class="permalink" href="#mail"><code class="Dv">mail</code></a></dt>
353 bd0bf387 2024-04-23 stsp <dd>Committer's mail address.</dd>
354 bd0bf387 2024-04-23 stsp <dt id="user~2"><a class="permalink" href="#user~2"><code class="Dv">user</code></a></dt>
355 bd0bf387 2024-04-23 stsp <dd>Committer's username. This is the only field guaranteed to
356 bd0bf387 2024-04-23 stsp be set.</dd>
359 bd0bf387 2024-04-23 stsp <dt id="author"><a class="permalink" href="#author"><code class="Dv">author</code></a></dt>
360 bd0bf387 2024-04-23 stsp <dd>An object with the author information. Has the same fields as
361 dfc34448 2024-05-06 stsp the ‘committer’ but may be unset.</dd>
362 bd0bf387 2024-04-23 stsp <dt id="date"><a class="permalink" href="#date"><code class="Dv">date</code></a></dt>
363 bd0bf387 2024-04-23 stsp <dd>Number, representing the number of seconds since the Epoch in
365 bd0bf387 2024-04-23 stsp <dt id="short_message"><a class="permalink" href="#short_message"><code class="Dv">short_message</code></a></dt>
366 bd0bf387 2024-04-23 stsp <dd>The first line of the commit message. This field is always
368 bd0bf387 2024-04-23 stsp <dt id="message"><a class="permalink" href="#message"><code class="Dv">message</code></a></dt>
369 bd0bf387 2024-04-23 stsp <dd>The complete commit message, may be unset.</dd>
370 bd0bf387 2024-04-23 stsp <dt id="diffstat"><a class="permalink" href="#diffstat"><code class="Dv">diffstat</code></a></dt>
371 bd0bf387 2024-04-23 stsp <dd>An object with the summarized changes, may be unset. Contains
372 dfc34448 2024-05-06 stsp a ‘files’ field with an array of objects
373 dfc34448 2024-05-06 stsp describing the changes per-file and a ‘total’
374 dfc34448 2024-05-06 stsp field with the cumulative changes. The changes per-file
375 dfc34448 2024-05-06 stsp contains the following fields:
376 bd0bf387 2024-04-23 stsp <p class="Pp"></p>
377 bd0bf387 2024-04-23 stsp <dl class="Bl-tag Bl-compact">
378 bd0bf387 2024-04-23 stsp <dt id="action"><a class="permalink" href="#action"><code class="Dv">action</code></a></dt>
379 bd0bf387 2024-04-23 stsp <dd>A string describing the action, can be
380 bd0bf387 2024-04-23 stsp “added”, “deleted”,
381 bd0bf387 2024-04-23 stsp “modified”, “mode changed”, or
382 bd0bf387 2024-04-23 stsp “unknown”.</dd>
383 bd0bf387 2024-04-23 stsp <dt id="file"><a class="permalink" href="#file"><code class="Dv">file</code></a></dt>
384 bd0bf387 2024-04-23 stsp <dd>The file path.</dd>
385 bd0bf387 2024-04-23 stsp <dt id="added"><a class="permalink" href="#added"><code class="Dv">added</code></a></dt>
386 bd0bf387 2024-04-23 stsp <dd>The number of lines added.</dd>
387 bd0bf387 2024-04-23 stsp <dt id="removed"><a class="permalink" href="#removed"><code class="Dv">removed</code></a></dt>
388 bd0bf387 2024-04-23 stsp <dd>The number of lines removed.</dd>
390 dfc34448 2024-05-06 stsp <p class="Pp">The ‘total’ object contains two
391 dfc34448 2024-05-06 stsp fields: ‘added’ and ‘removed’
392 dfc34448 2024-05-06 stsp which are the number of added and removed lines
393 dfc34448 2024-05-06 stsp respectively.</p>
397 bd0bf387 2024-04-23 stsp <dt id="branch-deleted"><a class="permalink" href="#branch-deleted"><code class="Dv">branch-deleted</code></a></dt>
398 bd0bf387 2024-04-23 stsp <dd>The branch deleted notifications has the following fields, all
399 bd0bf387 2024-04-23 stsp guaranteed to be set:
400 dfc34448 2024-05-06 stsp <dl class="Bl-tag">
401 bd0bf387 2024-04-23 stsp <dt id="ref"><a class="permalink" href="#ref"><code class="Dv">ref</code></a></dt>
402 bd0bf387 2024-04-23 stsp <dd>The removed branch reference.</dd>
403 bd0bf387 2024-04-23 stsp <dt id="id~2"><a class="permalink" href="#id~2"><code class="Dv">id</code></a></dt>
404 bd0bf387 2024-04-23 stsp <dd>The hash of the commit pointed by the deleted branch.</dd>
407 bd0bf387 2024-04-23 stsp <dt id="tag~2"><a class="permalink" href="#tag~2"><code class="Dv">tag</code></a></dt>
408 bd0bf387 2024-04-23 stsp <dd>The tag notification has the following fields, all guaranteed to
410 bd0bf387 2024-04-23 stsp <dl class="Bl-tag">
411 bd0bf387 2024-04-23 stsp <dt>tag</dt>
412 bd0bf387 2024-04-23 stsp <dd>The tag reference.</dd>
413 bd0bf387 2024-04-23 stsp <dt>tagger</dt>
414 bd0bf387 2024-04-23 stsp <dd>The user information, with the same format of the
415 dfc34448 2024-05-06 stsp ‘committer’ field for the ‘commit’
416 dfc34448 2024-05-06 stsp notification but with all the field guaranteed to be set.</dd>
417 bd0bf387 2024-04-23 stsp <dt id="date~2"><a class="permalink" href="#date~2"><code class="Dv">date</code></a></dt>
418 bd0bf387 2024-04-23 stsp <dd>Number, representing the number of seconds since the Epoch in
420 bd0bf387 2024-04-23 stsp <dt id="object"><a class="permalink" href="#object"><code class="Dv">object</code></a></dt>
421 bd0bf387 2024-04-23 stsp <dd>The object being tagged. It contains the fields
422 dfc34448 2024-05-06 stsp ‘type’ with the object type and
423 dfc34448 2024-05-06 stsp ‘id’ with the object id being tagged.</dd>
424 bd0bf387 2024-04-23 stsp <dt id="message~2"><a class="permalink" href="#message~2"><code class="Dv">message</code></a></dt>
425 bd0bf387 2024-04-23 stsp <dd>The tag message.</dd>
434 742bb3a1 2022-10-24 stsp <section class="Sh">
435 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
436 742bb3a1 2022-10-24 stsp <dl class="Bl-tag Bl-compact">
437 742bb3a1 2022-10-24 stsp <dt><span class="Pa">/etc/gotd.conf</span></dt>
438 742bb3a1 2022-10-24 stsp <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
441 742bb3a1 2022-10-24 stsp <section class="Sh">
442 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
443 742bb3a1 2022-10-24 stsp <div class="Bd Bd-indent Li">
444 47f19dd5 2023-01-17 stsp <pre># Run as the default user:
447 47f19dd5 2023-01-17 stsp # Listen on the default socket:
448 47f19dd5 2023-01-17 stsp listen on "/var/run/gotd.sock"
450 742bb3a1 2022-10-24 stsp # This repository can be accessed via ssh://user@example.com/src
451 742bb3a1 2022-10-24 stsp repository "src" {
452 742bb3a1 2022-10-24 stsp path "/var/git/src.git"
453 47f19dd5 2023-01-17 stsp permit rw flan_hacker
454 47f19dd5 2023-01-17 stsp permit rw :developers
455 47f19dd5 2023-01-17 stsp permit ro anonymous
457 e68eaba8 2023-04-20 stsp protect branch "main"
458 e68eaba8 2023-04-20 stsp protect tag namespace "refs/tags/"
461 742bb3a1 2022-10-24 stsp # This repository can be accessed via
462 742bb3a1 2022-10-24 stsp # ssh://user@example.com/openbsd/ports
463 742bb3a1 2022-10-24 stsp repository "openbsd/ports" {
464 742bb3a1 2022-10-24 stsp path "/var/git/ports.git"
465 47f19dd5 2023-01-17 stsp permit rw :porters
466 47f19dd5 2023-01-17 stsp permit ro anonymous
467 47f19dd5 2023-01-17 stsp deny flan_hacker
470 e68eaba8 2023-04-20 stsp branch "main"
471 e68eaba8 2023-04-20 stsp tag namespace "refs/tags/"
475 bd0bf387 2024-04-23 stsp branch "main"
476 bd0bf387 2024-04-23 stsp reference namespace "refs/tags/"
477 bd0bf387 2024-04-23 stsp email to openbsd-ports-changes@example.com
481 47f19dd5 2023-01-17 stsp # Use a larger request timeout value:
482 47f19dd5 2023-01-17 stsp connection request timeout 2h
484 47f19dd5 2023-01-17 stsp # Some users are granted a higher concurrent connection limit:
485 47f19dd5 2023-01-17 stsp connection {
486 47f19dd5 2023-01-17 stsp limit user flan_hacker 16
487 47f19dd5 2023-01-17 stsp limit user anonymous 32
491 742bb3a1 2022-10-24 stsp <section class="Sh">
492 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
493 742bb3a1 2022-10-24 stsp ALSO</a></h2>
494 742bb3a1 2022-10-24 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
495 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
496 7196cfe5 2024-09-09 stsp <a class="Xr" aria-label="gotd-secrets.conf, section
497 7196cfe5 2024-09-09 stsp 5">gotd-secrets.conf(5)</a>, <a class="Xr" aria-label="gotd, section
498 7196cfe5 2024-09-09 stsp 8">gotd(8)</a></p>
501 742bb3a1 2022-10-24 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
502 765eba91 2024-11-21 op line"><span class="foot-left"></span><span class="foot-date">November 21,
503 a3016eec 2024-10-22 op 2024</span> <span class="foot-os">OpenBSD 7.6</span></div>
