Version Control Services (GNU Guix Reference Manual)

10.8.27 Version Control Services

The (gnu services version-control) module provides a service to allow remote access to local Git repositories. There are three options: the git-daemon-service, which provides access to repositories via the git:// unsecured TCP-based protocol, extending the nginx web server to proxy some requests to git-http-backend, or providing a web interface with cgit-service-type.

Scheme Procedure: git-daemon-service [#:config (git-daemon-configuration)]

Return a service that runs git daemon, a simple TCP server to expose repositories over the Git protocol for anonymous access.

The optional config argument should be a <git-daemon-configuration> object, by default it allows read-only access to exported²⁹ repositories under /srv/git.

Data Type: git-daemon-configuration

Data type representing the configuration for git-daemon-service.

package (default: git): Package object of the Git distributed version control system.
export-all? (default: #f): Whether to allow access for all Git repositories, even if they do not have the git-daemon-export-ok file.
base-path (default: /srv/git): Whether to remap all the path requests as relative to the given path. If you run git daemon with (base-path "/srv/git") on ‘example.com’, then if you later try to pull ‘git://example.com/hello.git’, git daemon will interpret the path as /srv/git/hello.git.
user-path (default: #f): Whether to allow ~user notation to be used in requests. When specified with empty string, requests to ‘git://host/~alice/foo’ is taken as a request to access foo repository in the home directory of user alice. If (user-path "path") is specified, the same request is taken as a request to access path/foo repository in the home directory of user alice.
listen (default: '()): Whether to listen on specific IP addresses or hostnames, defaults to all.
port (default: #f): Whether to listen on an alternative port, which defaults to 9418.
whitelist (default: '()): If not empty, only allow access to this list of directories.
extra-options (default: '()): Extra options will be passed to git daemon, please run man git-daemon for more information.

The git:// protocol lacks authentication. When you pull from a repository fetched via git://, you don’t know whether the data you receive was modified or is even coming from the specified host, and your connection is subject to eavesdropping. It’s better to use an authenticated and encrypted transport, such as https. Although Git allows you to serve repositories using unsophisticated file-based web servers, there is a faster protocol implemented by the git-http-backend program. This program is the back-end of a proper Git web service. It is designed to sit behind a FastCGI proxy. See Web Services, for more on running the necessary fcgiwrap daemon.

Guix has a separate configuration data type for serving Git repositories over HTTP.

Data Type: git-http-configuration

Data type representing the configuration for a future git-http-service-type; can currently be used to configure Nginx through git-http-nginx-location-configuration.

package (default: git): Package object of the Git distributed version control system.
git-root (default: /srv/git): Directory containing the Git repositories to expose to the world.
export-all? (default: #f): Whether to expose access for all Git repositories in git-root, even if they do not have the git-daemon-export-ok file.
uri-path (default: ‘/git/’): Path prefix for Git access. With the default ‘/git/’ prefix, this will map ‘http://server/git/repo.git’ to /srv/git/repo.git. Requests whose URI paths do not begin with this prefix are not passed on to this Git instance.
fcgiwrap-socket (default: 127.0.0.1:9000): The socket on which the fcgiwrap daemon is listening. See Web Services.

There is no git-http-service-type, currently; instead you can create an nginx-location-configuration from a git-http-configuration and then add that location to a web server.

Scheme Procedure: git-http-nginx-location-configuration [config=(git-http-configuration)]

Compute an nginx-location-configuration that corresponds to the given Git http configuration. An example nginx service definition to serve the default /srv/git over HTTPS might be:

(service nginx-service-type
         (nginx-configuration
          (server-blocks
           (list
            (nginx-server-configuration
             (listen '("443 ssl"))
             (server-name "git.my-host.org")
             (ssl-certificate
              "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
             (ssl-certificate-key
              "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
             (locations
              (list
               (git-http-nginx-location-configuration
                (git-http-configuration (uri-path "/"))))))))))

This example assumes that you are using Let’s Encrypt to get your TLS certificate. See Certificate Services. The default certbot service will redirect all HTTP traffic on git.my-host.org to HTTPS. You will also need to add an fcgiwrap proxy to your system services. See Web Services.

Cgit Service

Cgit is a web frontend for Git repositories written in C.

The following example will configure the service with default values. By default, Cgit can be accessed on port 80 (http://localhost:80).

(service cgit-service-type)

The file-object type designates either a file-like object (see file-like objects) or a string.

Available cgit-configuration fields are:

cgit-configuration parameter: package package: The CGIT package.

cgit-configuration parameter: nginx-server-configuration-list nginx: NGINX configuration.

cgit-configuration parameter: file-object about-filter

Specifies a command which will be invoked to format the content of about pages (both top-level and for each repository).

Defaults to ‘""’.

cgit-configuration parameter: string agefile

Specifies a path, relative to each repository path, which can be used to specify the date and time of the youngest commit in the repository.

Defaults to ‘""’.

cgit-configuration parameter: file-object auth-filter

Specifies a command that will be invoked for authenticating repository access.

Defaults to ‘""’.

cgit-configuration parameter: string branch-sort

Flag which, when set to ‘age’, enables date ordering in the branch ref list, and when set ‘name’ enables ordering by branch name.

Defaults to ‘"name"’.

cgit-configuration parameter: string cache-root

Path used to store the cgit cache entries.

Defaults to ‘"/var/cache/cgit"’.

cgit-configuration parameter: integer cache-static-ttl

Number which specifies the time-to-live, in minutes, for the cached version of repository pages accessed with a fixed SHA1.

Defaults to ‘-1’.

cgit-configuration parameter: integer cache-dynamic-ttl

Number which specifies the time-to-live, in minutes, for the cached version of repository pages accessed without a fixed SHA1.

Defaults to ‘5’.

cgit-configuration parameter: integer cache-repo-ttl

Number which specifies the time-to-live, in minutes, for the cached version of the repository summary page.

Defaults to ‘5’.

cgit-configuration parameter: integer cache-root-ttl

Number which specifies the time-to-live, in minutes, for the cached version of the repository index page.

Defaults to ‘5’.

cgit-configuration parameter: integer cache-scanrc-ttl

Number which specifies the time-to-live, in minutes, for the result of scanning a path for Git repositories.

Defaults to ‘15’.

cgit-configuration parameter: integer cache-about-ttl

Number which specifies the time-to-live, in minutes, for the cached version of the repository about page.

Defaults to ‘15’.

cgit-configuration parameter: integer cache-snapshot-ttl

Number which specifies the time-to-live, in minutes, for the cached version of snapshots.

Defaults to ‘5’.

cgit-configuration parameter: integer cache-size

The maximum number of entries in the cgit cache. When set to ‘0’, caching is disabled.

Defaults to ‘0’.

cgit-configuration parameter: boolean case-sensitive-sort?

Sort items in the repo list case sensitively.

Defaults to ‘#t’.

cgit-configuration parameter: list clone-prefix

List of common prefixes which, when combined with a repository URL, generates valid clone URLs for the repository.

Defaults to ‘()’.

cgit-configuration parameter: list clone-url

List of clone-url templates.

Defaults to ‘()’.

cgit-configuration parameter: file-object commit-filter

Command which will be invoked to format commit messages.

Defaults to ‘""’.

cgit-configuration parameter: string commit-sort

Flag which, when set to ‘date’, enables strict date ordering in the commit log, and when set to ‘topo’ enables strict topological ordering.

Defaults to ‘"git log"’.

cgit-configuration parameter: file-object css

URL which specifies the css document to include in all cgit pages.

Defaults to ‘"/share/cgit/cgit.css"’.

cgit-configuration parameter: file-object email-filter

Specifies a command which will be invoked to format names and email address of committers, authors, and taggers, as represented in various places throughout the cgit interface.

Defaults to ‘""’.

cgit-configuration parameter: boolean embedded?

Flag which, when set to ‘#t’, will make cgit generate a HTML fragment suitable for embedding in other HTML pages.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-commit-graph?

Flag which, when set to ‘#t’, will make cgit print an ASCII-art commit history graph to the left of the commit messages in the repository log page.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-filter-overrides?

Flag which, when set to ‘#t’, allows all filter settings to be overridden in repository-specific cgitrc files.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-follow-links?

Flag which, when set to ‘#t’, allows users to follow a file in the log view.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-http-clone?

If set to ‘#t’, cgit will act as an dumb HTTP endpoint for Git clones.

Defaults to ‘#t’.

cgit-configuration parameter: boolean enable-index-links?

Flag which, when set to ‘#t’, will make cgit generate extra links "summary", "commit", "tree" for each repo in the repository index.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-index-owner?

Flag which, when set to ‘#t’, will make cgit display the owner of each repo in the repository index.

Defaults to ‘#t’.

cgit-configuration parameter: boolean enable-log-filecount?

Flag which, when set to ‘#t’, will make cgit print the number of modified files for each commit on the repository log page.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-log-linecount?

Flag which, when set to ‘#t’, will make cgit print the number of added and removed lines for each commit on the repository log page.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-remote-branches?

Flag which, when set to #t, will make cgit display remote branches in the summary and refs views.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-subject-links?

Flag which, when set to 1, will make cgit use the subject of the parent commit as link text when generating links to parent commits in commit view.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-html-serving?

Flag which, when set to ‘#t’, will make cgit use the subject of the parent commit as link text when generating links to parent commits in commit view.

Defaults to ‘#f’.

cgit-configuration parameter: boolean enable-tree-linenumbers?

Flag which, when set to ‘#t’, will make cgit generate linenumber links for plaintext blobs printed in the tree view.

Defaults to ‘#t’.

cgit-configuration parameter: boolean enable-git-config?

Flag which, when set to ‘#f’, will allow cgit to use Git config to set any repo specific settings.

Defaults to ‘#f’.

cgit-configuration parameter: file-object favicon

URL used as link to a shortcut icon for cgit.

Defaults to ‘"/favicon.ico"’.

cgit-configuration parameter: string footer

The content of the file specified with this option will be included verbatim at the bottom of all pages (i.e. it replaces the standard "generated by..." message).

Defaults to ‘""’.

cgit-configuration parameter: string head-include

The content of the file specified with this option will be included verbatim in the HTML HEAD section on all pages.

Defaults to ‘""’.

cgit-configuration parameter: string header

The content of the file specified with this option will be included verbatim at the top of all pages.

Defaults to ‘""’.

cgit-configuration parameter: file-object include

Name of a configfile to include before the rest of the current config- file is parsed.

Defaults to ‘""’.

cgit-configuration parameter: string index-header

The content of the file specified with this option will be included verbatim above the repository index.

Defaults to ‘""’.

cgit-configuration parameter: string index-info

The content of the file specified with this option will be included verbatim below the heading on the repository index page.

Defaults to ‘""’.

cgit-configuration parameter: boolean local-time?

Flag which, if set to ‘#t’, makes cgit print commit and tag times in the servers timezone.

Defaults to ‘#f’.

cgit-configuration parameter: file-object logo

URL which specifies the source of an image which will be used as a logo on all cgit pages.

Defaults to ‘"/share/cgit/cgit.png"’.

cgit-configuration parameter: string logo-link

URL loaded when clicking on the cgit logo image.

Defaults to ‘""’.

cgit-configuration parameter: file-object owner-filter

Command which will be invoked to format the Owner column of the main page.

Defaults to ‘""’.

cgit-configuration parameter: integer max-atom-items

Number of items to display in atom feeds view.

Defaults to ‘10’.

cgit-configuration parameter: integer max-commit-count

Number of entries to list per page in "log" view.

Defaults to ‘50’.

cgit-configuration parameter: integer max-message-length

Number of commit message characters to display in "log" view.

Defaults to ‘80’.

cgit-configuration parameter: integer max-repo-count

Specifies the number of entries to list per page on the repository index page.

Defaults to ‘50’.

cgit-configuration parameter: integer max-repodesc-length

Specifies the maximum number of repo description characters to display on the repository index page.

Defaults to ‘80’.

cgit-configuration parameter: integer max-blob-size

Specifies the maximum size of a blob to display HTML for in KBytes.

Defaults to ‘0’.

cgit-configuration parameter: string max-stats

Maximum statistics period. Valid values are ‘week’,‘month’, ‘quarter’ and ‘year’.

Defaults to ‘""’.

cgit-configuration parameter: mimetype-alist mimetype

Mimetype for the specified filename extension.

Defaults to ‘((gif "image/gif") (html "text/html") (jpg "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg "image/svg+xml"))’.

cgit-configuration parameter: file-object mimetype-file

Specifies the file to use for automatic mimetype lookup.

Defaults to ‘""’.

cgit-configuration parameter: string module-link

Text which will be used as the formatstring for a hyperlink when a submodule is printed in a directory listing.

Defaults to ‘""’.

cgit-configuration parameter: boolean nocache?

If set to the value ‘#t’ caching will be disabled.

Defaults to ‘#f’.

cgit-configuration parameter: boolean noplainemail?

If set to ‘#t’ showing full author email addresses will be disabled.

Defaults to ‘#f’.

cgit-configuration parameter: boolean noheader?

Flag which, when set to ‘#t’, will make cgit omit the standard header on all pages.

Defaults to ‘#f’.

cgit-configuration parameter: project-list project-list

A list of subdirectories inside of repository-directory, relative to it, that should loaded as Git repositories. An empty list means that all subdirectories will be loaded.

Defaults to ‘()’.

cgit-configuration parameter: file-object readme

Text which will be used as default value for cgit-repo-readme.

Defaults to ‘""’.

cgit-configuration parameter: boolean remove-suffix?

If set to #t and repository-directory is enabled, if any repositories are found with a suffix of .git, this suffix will be removed for the URL and name.

Defaults to ‘#f’.

cgit-configuration parameter: integer renamelimit

Maximum number of files to consider when detecting renames.

Defaults to ‘-1’.

cgit-configuration parameter: string repository-sort

The way in which repositories in each section are sorted.

Defaults to ‘""’.

cgit-configuration parameter: robots-list robots

Text used as content for the robots meta-tag.

Defaults to ‘("noindex" "nofollow")’.

cgit-configuration parameter: string root-desc

Text printed below the heading on the repository index page.

Defaults to ‘"a fast webinterface for the git dscm"’.

cgit-configuration parameter: string root-readme

The content of the file specified with this option will be included verbatim below the “about” link on the repository index page.

Defaults to ‘""’.

cgit-configuration parameter: string root-title

Text printed as heading on the repository index page.

Defaults to ‘""’.

cgit-configuration parameter: boolean scan-hidden-path

If set to ‘#t’ and repository-directory is enabled, repository-directory will recurse into directories whose name starts with a period. Otherwise, repository-directory will stay away from such directories, considered as “hidden”. Note that this does not apply to the .git directory in non-bare repos.

Defaults to ‘#f’.

cgit-configuration parameter: list snapshots

Text which specifies the default set of snapshot formats that cgit generates links for.

Defaults to ‘()’.

cgit-configuration parameter: repository-directory repository-directory

Name of the directory to scan for repositories (represents scan-path).

Defaults to ‘"/srv/git"’.

cgit-configuration parameter: string section

The name of the current repository section - all repositories defined after this option will inherit the current section name.

Defaults to ‘""’.

cgit-configuration parameter: string section-sort

Flag which, when set to ‘1’, will sort the sections on the repository listing by name.

Defaults to ‘""’.

cgit-configuration parameter: integer section-from-path

A number which, if defined prior to repository-directory, specifies how many path elements from each repo path to use as a default section name.

Defaults to ‘0’.

cgit-configuration parameter: boolean side-by-side-diffs?

If set to ‘#t’ shows side-by-side diffs instead of unidiffs per default.

Defaults to ‘#f’.

cgit-configuration parameter: file-object source-filter

Specifies a command which will be invoked to format plaintext blobs in the tree view.

Defaults to ‘""’.

cgit-configuration parameter: integer summary-branches

Specifies the number of branches to display in the repository “summary” view.

Defaults to ‘10’.

cgit-configuration parameter: integer summary-log

Specifies the number of log entries to display in the repository “summary” view.

Defaults to ‘10’.

cgit-configuration parameter: integer summary-tags

Specifies the number of tags to display in the repository “summary” view.

Defaults to ‘10’.

cgit-configuration parameter: string strict-export

Filename which, if specified, needs to be present within the repository for cgit to allow access to that repository.

Defaults to ‘""’.

cgit-configuration parameter: string virtual-root

URL which, if specified, will be used as root for all cgit links.

Defaults to ‘"/"’.

cgit-configuration parameter: repository-cgit-configuration-list repositories

A list of cgit-repo records to use with config.

Defaults to ‘()’.

Available repository-cgit-configuration fields are:

repository-cgit-configuration parameter: repo-list snapshots

A mask of snapshot formats for this repo that cgit generates links for, restricted by the global snapshots setting.

Defaults to ‘()’.

repository-cgit-configuration parameter: repo-file-object source-filter

Override the default source-filter.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string url

The relative URL used to access the repository.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-file-object about-filter

Override the default about-filter.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string branch-sort

Flag which, when set to ‘age’, enables date ordering in the branch ref list, and when set to ‘name’ enables ordering by branch name.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-list clone-url

A list of URLs which can be used to clone repo.

Defaults to ‘()’.

repository-cgit-configuration parameter: repo-file-object commit-filter

Override the default commit-filter.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string commit-sort

Flag which, when set to ‘date’, enables strict date ordering in the commit log, and when set to ‘topo’ enables strict topological ordering.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string defbranch

The name of the default branch for this repository. If no such branch exists in the repository, the first branch name (when sorted) is used as default instead. By default branch pointed to by HEAD, or “master” if there is no suitable HEAD.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string desc

The value to show as repository description.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string homepage

The value to show as repository homepage.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-file-object email-filter

Override the default email-filter.

Defaults to ‘""’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-commit-graph?

A flag which can be used to disable the global setting enable-commit-graph?.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-log-filecount?

A flag which can be used to disable the global setting enable-log-filecount?.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-log-linecount?

A flag which can be used to disable the global setting enable-log-linecount?.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-remote-branches?

Flag which, when set to #t, will make cgit display remote branches in the summary and refs views.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-subject-links?

A flag which can be used to override the global setting enable-subject-links?.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: maybe-repo-boolean enable-html-serving?

A flag which can be used to override the global setting enable-html-serving?.

Defaults to ‘disabled’.

repository-cgit-configuration parameter: repo-boolean hide?

Flag which, when set to #t, hides the repository from the repository index.

Defaults to ‘#f’.

repository-cgit-configuration parameter: repo-boolean ignore?

Flag which, when set to ‘#t’, ignores the repository.

Defaults to ‘#f’.

repository-cgit-configuration parameter: repo-file-object logo

URL which specifies the source of an image which will be used as a logo on this repo’s pages.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string logo-link

URL loaded when clicking on the cgit logo image.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-file-object owner-filter

Override the default owner-filter.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string module-link

Text which will be used as the formatstring for a hyperlink when a submodule is printed in a directory listing. The arguments for the formatstring are the path and SHA1 of the submodule commit.

Defaults to ‘""’.

repository-cgit-configuration parameter: module-link-path module-link-path

Text which will be used as the formatstring for a hyperlink when a submodule with the specified subdirectory path is printed in a directory listing.

Defaults to ‘()’.

repository-cgit-configuration parameter: repo-string max-stats

Override the default maximum statistics period.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string name

The value to show as repository name.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string owner

A value used to identify the owner of the repository.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string path

An absolute path to the repository directory.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string readme

A path (relative to repo) which specifies a file to include verbatim as the “About” page for this repo.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-string section

The name of the current repository section - all repositories defined after this option will inherit the current section name.

Defaults to ‘""’.

repository-cgit-configuration parameter: repo-list extra-options

Extra options will be appended to cgitrc file.

Defaults to ‘()’.

cgit-configuration parameter: list extra-options

Extra options will be appended to cgitrc file.

Defaults to ‘()’.

However, it could be that you just want to get a cgitrc up and running. In that case, you can pass an opaque-cgit-configuration as a record to cgit-service-type. As its name indicates, an opaque configuration does not have easy reflective capabilities.

Available opaque-cgit-configuration fields are:

opaque-cgit-configuration parameter: package cgit: The cgit package.

opaque-cgit-configuration parameter: string string: The contents of the cgitrc, as a string.

For example, if your cgitrc is just the empty string, you could instantiate a cgit service like this:

(service cgit-service-type
         (opaque-cgit-configuration
          (cgitrc "")))

Gitolite Service

Gitolite is a tool for hosting Git repositories on a central server.

Gitolite can handle multiple repositories and users, and supports flexible configuration of the permissions for the users on the repositories.

The following example will configure Gitolite using the default git user, and the provided SSH public key.

(service gitolite-service-type
         (gitolite-configuration
           (admin-pubkey (plain-file
                           "yourname.pub"
                           "ssh-rsa AAAA... guix@example.com"))))

Gitolite is configured through a special admin repository which you can clone, for example, if you setup Gitolite on example.com, you would run the following command to clone the admin repository.

git clone git@example.com:gitolite-admin

When the Gitolite service is activated, the provided admin-pubkey will be inserted in to the keydir directory in the gitolite-admin repository. If this results in a change in the repository, it will be committed using the message “gitolite setup by GNU Guix”.

Data Type: gitolite-configuration

Data type representing the configuration for gitolite-service-type.

package (default: gitolite)

Gitolite package to use.

user (default: git)

User to use for Gitolite. This will be user that you use when accessing Gitolite over SSH.

group (default: git)

Group to use for Gitolite.

home-directory (default: "/var/lib/gitolite")

Directory in which to store the Gitolite configuration and repositories.

rc-file (default: (gitolite-rc-file))

A “file-like” object (see file-like objects), representing the configuration for Gitolite.

admin-pubkey (default: #f)

A “file-like” object (see file-like objects) used to setup Gitolite. This will be inserted in to the keydir directory within the gitolite-admin repository.

To specify the SSH key as a string, use the plain-file function.

(plain-file "yourname.pub" "ssh-rsa AAAA... guix@example.com")

Data Type: gitolite-rc-file

Data type representing the Gitolite RC file.

umask (default: #o0077)

This controls the permissions Gitolite sets on the repositories and their contents.

A value like #o0027 will give read access to the group used by Gitolite (by default: git). This is necessary when using Gitolite with software like cgit or gitweb.

unsafe-pattern (default: #f)

An optional Perl regular expression for catching unsafe configurations in the configuration file. See Gitolite’s documentation for more information.

When the value is not #f, it should be a string containing a Perl regular expression, such as ‘"[`~#\$\&()|;<>]"’, which is the default value used by gitolite. It rejects any special character in configuration that might be interpreted by a shell, which is useful when sharing the administration burden with other people that do not otherwise have shell access on the server.

git-config-keys (default: "")

Gitolite allows you to set git config values using the ‘config’ keyword. This setting allows control over the config keys to accept.

roles (default: '(("READERS" . 1) ("WRITERS" . )))

Set the role names allowed to be used by users running the perms command.

enable (default: '("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb"))

This setting controls the commands and features to enable within Gitolite.

Gitile Service

Gitile is a Git forge for viewing public git repository contents from a web browser.

Gitile works best in collaboration with Gitolite, and will serve the public repositories from Gitolite by default. The service should listen only on a local port, and a webserver should be configured to serve static resources. The gitile service provides an easy way to extend the Nginx service for that purpose (see NGINX).

The following example will configure Gitile to serve repositories from a custom location, with some default messages for the home page and the footers.

(service gitile-service-type
         (gitile-configuration
           (repositories "/srv/git")
           (base-git-url "https://myweb.site/git")
           (index-title "My git repositories")
           (intro '((p "This is all my public work!")))
           (footer '((p "This is the end")))
           (nginx-server-block
             (nginx-server-configuration
               (ssl-certificate
                 "/etc/letsencrypt/live/myweb.site/fullchain.pem")
               (ssl-certificate-key
                 "/etc/letsencrypt/live/myweb.site/privkey.pem")
               (listen '("443 ssl http2" "[::]:443 ssl http2"))
               (locations
                 (list
                   ;; Allow for https anonymous fetch on /git/ urls.
                   (git-http-nginx-location-configuration
                     (git-http-configuration
                       (uri-path "/git/")
                       (git-root "/var/lib/gitolite/repositories")))))))))

In addition to the configuration record, you should configure your git repositories to contain some optional information. First, your public repositories need to contain the git-daemon-export-ok magic file that allows Git to export the repository. Gitile uses the presence of this file to detect public repositories it should make accessible. To do so with Gitolite for instance, modify your conf/gitolite.conf to include this in the repositories you want to make public:

repo foo
    R = daemon

In addition, Gitile can read the repository configuration to display more information on the repository. Gitile uses the gitweb namespace for its configuration. As an example, you can use the following in your conf/gitolite.conf:

repo foo
    R = daemon
    desc = A long description, optionally with <i>HTML</i>, shown on the index page
    config gitweb.name = The Foo Project
    config gitweb.synopsis = A short description, shown on the main page of the project

Do not forget to commit and push these changes once you are satisfied. You may need to change your gitolite configuration to allow the previous configuration options to be set. One way to do that is to add the following service definition:

(service gitolite-service-type
          (gitolite-configuration
            (admin-pubkey (local-file "key.pub"))
            (rc-file
              (gitolite-rc-file
                (umask #o0027)
                ;; Allow to set any configuration key
                (git-config-keys ".*")
                ;; Allow any text as a valid configuration value
                (unsafe-patt "^$")))))

Data Type: gitile-configuration

Data type representing the configuration for gitile-service-type.

package (default: gitile)

Gitile package to use.

host (default: "localhost")

The host on which gitile is listening.

port (default: 8080)

The port on which gitile is listening.

database (default: "/var/lib/gitile/gitile-db.sql")

The location of the database.

repositories (default: "/var/lib/gitolite/repositories")

The location of the repositories. Note that only public repositories will be shown by Gitile. To make a repository public, add an empty git-daemon-export-ok file at the root of that repository.

base-git-url

The base git url that will be used to show clone commands.

index-title (default: "Index")

The page title for the index page that lists all the available repositories.

intro (default: '())

The intro content, as a list of sxml expressions. This is shown above the list of repositories, on the index page.

footer (default: '())

The footer content, as a list of sxml expressions. This is shown on every page served by Gitile.

nginx-server-block

An nginx server block that will be extended and used as a reverse proxy by Gitile to serve its pages, and as a normal web server to serve its assets.

You can use this block to add more custom URLs to your domain, such as a /git/ URL for anonymous clones, or serving any other files you would like to serve.

Footnotes

(29)

By creating the magic file git-daemon-export-ok in the repository directory.