Cgit Setup

2023-08-03

Below is my cgit setup. Setting up cgit is not too complex, but it can be tricky from my experience.

Installation

I use fcgiwrap to call cgit from Nginx.

apt install cgit fcgiwrap

Nginx

I create a snippet that encapsulates the cgit setup. I then include this snippet from my default site.

/etc/nginx/snippets/cgit.conf

location /cgit {
    include             fastcgi_params;
    fastcgi_param       SCRIPT_FILENAME /usr/lib/cgit/cgit.cgi;
    fastcgi_split_path_info ^(/cgit/?)(.+)$;
    fastcgi_param       PATH_INFO    $fastcgi_path_info;
    fastcgi_param       QUERY_STRING $args;
    fastcgi_param       HTTP_HOST    $server_name;
    fastcgi_pass        unix:/run/fcgiwrap.socket;
}

/etc/nginx/sites-available/default

server {
  ...

  include /etc/nginx/snippets/cgit.conf;
}

The specific values in cgit.conf will vary across setups. You need to change them for your setup.

In my case, cgit is served from /cgit/. Therefore, the location is location /cgit so that Nginx invokes cgit when a user queries this location.

Another point is that I need to strip the /cgit/ part from the path that is forwarded to cgit. That is what fastcgi_split_path_info does. This variable requires two regex captures, the second of which becomes $fastcgi_path_info. This is the variable that I then pass as PATH_INFO.

Finally, the values /usr/lib/cgit/cgit.cgi and unix:/run/fcgiwrap.socket might be different across Linux distributions. You should check what these values are in your case.

Permissions

cgit runs under whatever user Nginx runs with, typically www-data. This user must have read access to your git repositories. If cgit prints “No repositories found” and you are certain that it is pointed to the correct path to your git repositories (see next section), chances are the permissions are not correct.

Cgit

Below are relevant bits of my cgitrc. All of the values are documented in man cgitrc. Check the man page for further customization.

The first order of business is to point cgit to the git repositories on the system. I keep mine under /opt/git/.

scan-path=/opt/git/

To have cgit display README.md files and format the markdown, add the two lines below. The markdown formatting requires the markdown Python package. It is available on Ubuntu/Debian as python3-markdown.

apt install python3-markdown

readme=main:README.md
about-filter=/usr/lib/cgit/filters/about-formatting.sh

To enable code syntax highlighting:

source-filter=/usr/lib/cgit/filters/syntax-highlighting.py

I haven’t figured out how to make cgit display the About/readme page by default instead of the summary page…

References

I set up cgit based on the references below. These were of great help.

https://wiki.archlinux.org/title/Cgit

https://bbs.archlinux.org/viewtopic.php?id=194743

https://blog.stefan-koch.name/2020/02/16/installing-cgit-nginx-on-debian

https://github.com/anujsharma12feb/cgit-fcgiwrap-nginx/wiki