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&timestamp=%d user "flan_announcer" password "secret"
+	}
 }
 
 # Use a larger request timeout value: