Ubuntu Manpage: gotd.conf — gotd configuration file

NAME

       gotd.conf — gotd configuration file

DESCRIPTION

       gotd.conf is the run-time configuration file for gotd(8).

       The  file  format is line-based, with one configuration directive per line.  Comments can be put anywhere
       in the file using a hash mark (‘#’), and extend to the end of the  current  line.   Arguments  names  not
       beginning  with  a  letter, digit or underscore, as well as reserved words (such as listen, repository or
       user), must be quoted.  Arguments containing whitespace should be surrounded by double quotes (").

       Macros can be defined that are later expanded in context.  Macro names must start with a  letter,  digit,
       or  underscore,  and  may contain any of those characters, but may not be reserved words.  Macros are not
       expanded inside quotes.  For example:

             path = "/var/run/gotd.sock"
             listen on $path

GLOBAL CONFIGURATION

The available global configuration directives are as follows:

connection option
Set the specified options and limits for connections to the gotd(8) unix socket.

The connection directive may be specified multiple times, and multiple option arguments may be
specified within curly braces:

connection {...}

Each option should only be specified once. If a given option is listed multiple times, the last
line which sets this option wins.

Valid connection options are:

request timeout seconds
Specify the inactivity timeout for operations between client and server. If this timeout
is exceeded while a Git protocol request is being processed, the request will be aborted
and the connection will be terminated.

The timeout value may also have a suffix indicating its unit of measure. Supported
suffixes are:

s or S seconds
m or M minutes
h or H hours

The default timeout is 1h (3600 seconds, one hour). This should only be changed if
legitimate requests are exceeding the default timeout for some reason, such as the server
spending an extraordinary amount of time generating a pack file.

limit user identity number
Limit the maximum amount of concurrent connections by the user with the username identity
to number. Numeric user IDs are also accepted.

The default per-user limit is 4. This should only be changed if concurrent connections
from a given user are expected to exceed the default limit, for example if an anonymous
user is granted read access and many concurrent connections will share this anonymous
user identity.

listen on path
Set the path to the unix socket which gotd(8) should listen on. If not specified, the path
/var/run/gotd.sock will be used.

user user
Set the user which will run gotd(8). Initially, gotd(8) requires root privileges in order to
create its unix socket. Afterwards, gotd(8) drops privileges to the specified user. If not
specified, the user _gotd will be used. Numeric user IDs are also accepted.

REPOSITORY CONFIGURATION

At least one repository context must exist for gotd(8) to function. For each repository, access rules
must be configured using the permit and deny configuration directives. Multiple access rules can be
specified, and the last matching rule determines the action taken. If no rule matches, access to the
repository is denied.

A repository context is declared with a unique name, followed by repository-specific configuration
directives inside curly braces:

repository name {...}

got(1) and git(1) clients can connect to a repository by including the repository's unique name in the
request URL. Clients appending the string “.git” to the name will also be accepted.

If desired, the name may contain path-separators, “/”, to expose repositories as part of a virtual
client-visible directory hierarchy.

The available repository configuration directives are as follows:

deny identity
Deny repository access to users with the username identity. Group names may be matched by
prepending a colon (‘:’) to identity. Numeric IDs are also accepted.

path path
Set the path to the Git repository. Must be specified.

permit mode identity
Permit repository access to users with the username identity. The mode argument must be set to
either ro for read-only access, or rw for read-write access. Group names may be matched by
prepending a colon (‘:’) to identity. Numeric IDs are also accepted.

protect {...}
The protect directive may be used to protect branches and tags in a repository from being
overwritten by potentially destructive client-side commands, such as when got send -f and git
push -f are used to change the history of a branch.

To build a set of protected branches and tags, multiple protect directives may be specified per
repository and multiple protect directive parameters may be specified within curly braces.

The available protect parameters are as follows:

branch name
Protect the named branch. The branch may be created if it does not exist yet. Attempts
to delete the branch or change its history will be denied.

If the name does not already begin with “refs/heads/” it will be looked up in the
“refs/heads/” reference namespace.

branch namespace namespace
Protect the given reference namespace, assuming that references in this namespace
represent branches. New branches may be created in the namespace. Attempts to change
the history of branches or delete them will be denied.

The namespace argument must be absolute, starting with “refs/”.

tag namespace namespace
Protect the given reference namespace, assuming that references in this namespace
represent tags. New tags may be created in the namespace. Attempts to change or delete
existing tags will be denied.

The namespace argument must be absolute, starting with “refs/”.

The special reference namespaces “refs/got/” and “refs/remotes/” do not need to be listed in
gotd.conf. These namespaces are always protected and even attempts to create new references in
these namespaces will always be denied.

notify {...}
The notify directive enables notifications about new commits or tags added to the repository.

Notifications via email require an SMTP daemon which accepts mail for forwarding without
requiring client authentication or encryption. On OpenBSD the smtpd(8) daemon can be used for
this purpose. The default content of email notifications looks similar to the output of the got
log -d command.

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 gotd(8) by triggering arbitrary post-
commit actions via the HTTP server.

The notify directive expects parameters which must be enclosed in curly braces. The available
parameters are as follows:

branch name
Send notifications about commits to the named branch. The name will be looked up in the
“refs/heads/” reference namespace. This directive may be specified multiple times to
build a list of branches to send notifications for. If neither a branch nor a reference
namespace are specified then changes to any reference will trigger notifications.

reference namespace 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 branch nor a reference namespace are specified then changes to any reference
will trigger notifications.

email [from sender] to recipient [reply to responder] [relay hostname [port port]]
Send notifications via email to the specified recipient. This directive may be specified
multiple times to build a list of recipients to send notifications to.

The recipient must be an email addresses that accepts mail. The sender will be used as
the From address. If not specified, the sender defaults to an email address composed of
the user account running gotd(8) and the local hostname.

If a responder is specified via the reply to directive, the responder will be used as the
Reply-to address. Setting the Reply-to header can be useful if replies should go to a
mailing list instead of the sender, for example.

By default, mail will be sent to the SMTP server listening on the loopback address
127.0.0.1 on port 25. The relay and port directives can be used to specify a different
SMTP server address and port.

url URL [auth label [insecure]] [hmac label]
Send notifications via HTTP. This directive may be specified multiple times to build a
list of HTTP servers to send notifications to.

The notification will be sent as a POST request to the given URL, which must be a valid
HTTP URL and begin with either “http://” or “https://”. If HTTPS is used, sending of
notifications will only succeed if no TLS errors occur.

The optional auth directive enables HTTP Basic authentication. Authentication
credentials must be specified in the separate gotd-secrets.conf(5) file, using the label
as identifier. Unless the insecure option is specified the notification target URL must
be a “https://” URL to avoid leaking of authentication credentials.

If a hmac secret is provided, the request body will be signed using HMAC, allowing the
receiver to verify the notification message's authenticity and integrity. The HMAC
secret to use must be specified in the separate gotd-secrets.conf(5) file, using the
label as identifier. The signature uses HMAC-SHA256 and will be sent in the HTTP header
“X-Gotd-Signature”.

The request body contains a JSON object with a “notifications” property containing an
array of notification objects. The following notification object properties are always
present:

repo The repository name as a string.

authenticated_user The committer's user account as authenticated by gotd(8) as a string.

type The notification object type as a string.

Each notification object carries additional type-specific properties. The types and
their type-specific properties are:

commit The commit notification object has the following fields. Except where noted, all
are optional.

short Boolean, indicates whether the object has all the fields set. When
several commits are batched in a single send operation, not all of the
fields are available for each commit object.

id The commit ID as string, may be abbreviated.

committer
An object with the committer information with the following fields:

full Committer's full name.
name Committer's name.
mail Committer's mail address.
user Committer's username. This is the only field guaranteed to be
set.

author An object with the author information. Has the same fields as the
‘committer’ but may be unset.

date Number, representing the number of seconds since the Epoch in UTC.

short_message
The first line of the commit message. This field is always set.

message
The complete commit message, may be unset.

diffstat
An object with the summarized changes, may be unset. Contains a ‘files’
field with an array of objects describing the changes per-file and a
‘total’ field with the cumulative changes. The changes per-file contains
the following fields:

action A string describing the action, can be “added”, “deleted”,
“modified”, “mode changed”, or “unknown”.
file The file path.
added The number of lines added.
removed The number of lines removed.

The ‘total’ object contains two fields: ‘added’ and ‘removed’ which are
the number of added and removed lines respectively.

branch-deleted
The branch deleted notifications has the following fields, all guaranteed to be
set:

ref The removed branch reference.

id The hash of the commit pointed by the deleted branch.

tag The tag notification has the following fields, all guaranteed to be set:

tag The tag reference.

tagger The user information, with the same format of the ‘committer’ field for
the ‘commit’ notification but with all the field guaranteed to be set.

date Number, representing the number of seconds since the Epoch in UTC.

object The object being tagged. It contains the fields ‘type’ with the object
type and ‘id’ with the object id being tagged.

message
The tag message.

FILES

       /etc/gotd.conf
               Location of the gotd.conf configuration file.

EXAMPLES