commit 518fc9bf283a8410fd83a49addb3662f8b119498 from: Stefan Sperling date: Mon Mar 11 09:49:07 2024 UTC document gotd notification feature commit - 5737d679619ac7bfa357277e0508f62d544d8385 commit + 518fc9bf283a8410fd83a49addb3662f8b119498 blob - 09928aa29395cb1acfaff6303c26cda1adfaf34a blob + 0c70d255091e9b4ab2a00bb736d8ea7eb7a82dda --- gotd/gotd.conf.5 +++ gotd/gotd.conf.5 @@ -237,7 +237,157 @@ do not need to be listed in .Nm . These namespaces are always protected and even attempts to create new references in these namespaces will always be denied. +.It Ic notify Brq Ar ... +The +.Ic notify +directive enables notifications about new commits or tags +added to the repository. +Notifications can be sent either via email or via HTTP. +.Pp +Notifications via email require an SMTP daemon listening on localhost which +is accepting mail for forwarding without requiring client authentication or +encryption. +On +.Ox +the +.Xr smtpd 8 +daemon can be used for this purpose. +The default content of email notifications looks similar to the output of the +.Cm got log +command. +.Pp +Notifications via HTTP require a HTTP or HTTPS server which is accepting +POST requests with or without HTTP Basic authentication. +Depending on the use case a custom server-side CGI script may be required +for the processing of notifications. +HTTP notifications can achieve functionality +similar to Git's server-side post-receive hook script with +.Xr gotd 8 +by triggering arbitrary post-commit actions via the HTTP server. +.Pp +The +.Ic notify +directive expects parameters which must be enclosed in curly braces. +The available parameters are as follows: +.Pp +.Bl -tag -width Ds +.It Ic branch Ar name +Send notifications about commits to the named branch. +The +.Ar name +will be looked up in the +.Dq refs/heads/ +reference namespace. +This directive may be specified multiple times to build a list of +branches to send notifications for. +If neither a +.Ic branch +nor a +.Ic reference namespace +are specified then changes to any reference will trigger notifications. +.It Ic reference Ic namespace Ar namespace +Send notifications about commits or tags within a reference namespace. +This directive may be specified multiple times to build a list of +namespaces to send notifications for. +If neither a +.Ic branch +nor a +.Ic reference namespace +are specified then changes to any reference will trigger notifications. +.It Ic summarize +Summarize notifications received in the same client session. +If not specified then default to sending a seperate notification for each +received commit or tag. +Notifications will always be summarized as soon as the amount of commits +or tags received in a given session exceeds an implementation-defined limit. +Each session corresponds to an invocation of a client-side command such as +.Cm got send +or +.Cm git push . +.It Ic email Ar recipient Oo Ic shortlog Oc Oo Ic with diff Oc +Send notifications via email to the specified +.Ar recipient +address, which must be a valid email address. +This directive may be specified multiple times to build a list of +recipient addresses to send notifications to. +.Pp +The commit or tag message will be sent in the email body. +If the optional +.Ic shortlog +directive is given, only the first line of the commit or tag message +will be sent. +.Pp +The optional +.Ic with diff +directive enables the display of committed changes in the email body +following the log message, similar to the output of +.Cm got log -p . +The +.Ic with diff +directive has no effect for tags. +.It Ic url Ar URL Oo Ic shortlog Oc Oo Ic user Ar user Ic password Ar password Oc +Send notifications via HTTP. +This directive may be specified multiple times to build a list of +HTTP servers to send notifications to. +.Pp +The notification will be sent as a POST request to the given +.Ar URL , +which must be a valid HTTP URL and begin with either +.Dq http:// +or +.Dq https:// . +If HTTPS is used, sending of notifications will only succeed if +no TLS errors occur. +.Pp +The commit or tag message will be sent in the request body. +If the optional +.Ic shortlog +directive is given, only the first line of the commit or tag message +will be sent. +.Pp +The optional +.Ic user +and +.Ic password +directives enable HTTP Basic authentication. +If used, both a +.Ar user +and a +.Ar password +must be specified. +The +.Ar password +must not be an empty string. +.Pp +The +.Ar URL +may contain values expanded via one or more format string directives. +Special characters in expanded values will be URL-encoded. +The supported format string directives are as follows: +.Bl -tag -width Ds +.It %a +Name and email address of the author. +.It %c +Name and email address of the committer. +.It %d +Committer timestamp in seconds since the UNIX epoch. +.It %D +Author timestamp in seconds since the UNIX epoch. +.It %t +Object type. +Expands to either +.Dq commit +or +.Dq tag +(without quotes). +.It %x +Object ID as a hexadecimal string. +.It %% +Expands to a literal +.Dq % +(without quotes). .El +.El .Sh FILES .Bl -tag -width Ds -compact .It Pa /etc/gotd.conf @@ -276,6 +426,14 @@ repository "openbsd/ports" { branch "main" tag namespace "refs/tags/" } + + notify { + branch "main" + reference namespace "refs/tags/" + summarize + email openbsd-ports-changes@example.com with diff + url https://example.com/?id=%x&type=%tcommitter=%c×tamp=%d user "flan_announcer" password "secret" + } } # Use a larger request timeout value: