Gitsune¶

I present to the general public: gitsune!

Gitsune is a git forge based on top of gitolite and git. It was written due to me wanting some software that does the following:

• provide all features I'd use out of a modern forge (taking forgejo and sourcehut as my examples)
• have "account" and repository management be as simple as it is on gitolite (like using ssh keys instead of passwords)
• allow anyone to contribute as long as they have an email address

This lead to the following featureset:

• SSH-key based login: we use gitolite's keydir to provide login
• native file rendering: uses python-markdown and pygments to render git blobs, uses custom code and html tables to display git tree objects
• smart http cloning: "outsources" this to git's CGI smart-cloning script, via gitolite-shell for authorisation
• feature-rich logviewer: features a checkout link, full description (not just summary) viewing, author and commit date fields (though sadly lacks a graph and any form of ranges...)
• webhooks: automatically picks either a subset of github's webhook packets, or a nice discord embed when the URL contains discord
• and bug/patch tracking (acit-style) will eventually arrive too!

The name¶

The name, Gitsune, is a combination of the name of the kitsune, a japanese mythical fox creature, and our favorite version control system, git.

Notes (READ THIS before deploying)¶

• Gitsune works with a plugin architecture. Most features are a plugin you can enable/disable.
• Gitsune does not support Partial Copy access control. It may work accidentally, but don't expect it to.
• You can enable and disable any plugin, but that does not mean the plugin won't be linked to. So disabling plugins like tree and objectviewer will probably give you dead links.
• Disabling the taskqueue plugin breaks the explore page.
• Gitsune does not support "Old style multi-keys", as the gitolite manual calls them. See commit 130363cc.
• Gitsune works way better with wild repos. While config-defined repos work, a lot of features (at least all that depend on knowing the repo owner) will break.
  • you can work around this by doing something like echo -n yourkeyname > repositories/$REPO.git/gl-creator, but I don't recommend it. recreate your repos instead.
• To massively increase authentication speed, read ## fastauth.
• Just like gitolite, gitsune does not always delete old data, it might instead 'forget' about the data's existence. This is a list of data that isn't deleted:
  • [all] data of plugins that were enabled and are no longer enabled
  • [account] allowed_signers lists of deleted/inactive users
  • possibly more that I did not add (yet)
    you'll have to remove this data yourself.

Setup¶

If you are using the docker container, you can skip this (unless you're migrating an existing install).

• Gitsune uses LOCAL_CODE to do a lot of stuff. Set up LOCAL_CODE, I personally use /var/lib/git/local for it.
• Then place scripts/hook_post-receive.sh in it as hooks/common/post-receive, and make sure it's executable
• Now install scripts/trigger_post_create.sh as a hook called gitsune:
  • Copy the file as triggers/gitsune, make sure it's executable.
  • Make sure to add gitsune to your list of POST_CREATE triggers (put POST_CREATE => [ 'gitsune', ], right before your ENABLE section, see the gitolite docs)

Docker¶

The image has been only tested on podman. If you encounter any bugs using docker, feel free to report them. Note the build instructions will apply to podman.

Building the container is quite straightforward: podman build -t gitsune .. You can now deploy this, for example using a compose.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

services:
  gitsune:
    image: gitsune
    volumes:
      - ./gitsune.toml:/var/lib/git/gitsune.toml
      - ./git:/var/lib/git/
    #environment:
    #  - DEBUG=10 # do not enable DEBUG in prod :)
    ports:
      - "8080:8080"
      - "22:22"

If you encounter an error while building that there is no pyproject.toml, explicitly mount the repo with the z flag: podman build -t gitsune -v $PWD:/source:z .

To do development using this image, mount the repo root at /gitsune, optionally read-only:

1

podman create --name gitsune -e DEBUG=10 -v $PWD:/gitsune:ro -v /tmp/admin.pub:/admin.pub:z -p8080:8080 -p8022:22 gitsune

KNOWN BUGS:¶

• if something provides invalid input to fastauth resulting in gitolite exiting (should be very difficult), the next request that does accesschecks will always return 403
• lack of documentation
• no log graphs :( (not really a bug but it is something I'd like to have)
• there's a possibility for multiple JsonFile() classes to the same file existing. solution would be to make a .deletelater() function and keep it in the refs until then.

LOGLEVELS:¶

Set the loglevel with the DEBUG env. Do not enable this in production.

1. stuff that happens often but not always
2. expansion of 1
3. very verbose logging
4. the secret loglevel that unlocks even more logmessages

TODO¶

• bug reporting
  • ways to subscribe to bugreports
  • a way to delete stuff
  • bug metadata (status, maybe type, etc)
• task runners (basically simple CI/CD)
• cgit-style categories on the explore page
• the bugs in ## KNOWN BUGS
• user documentation
• admin docs if I feel like it

fastauth¶

Before the fastauth plugin, gitsune spawned a new gitolite process every time it wanted to check a permission (so at least once per request, for most plugins). This took a lot of time. fastauth (for fast authorisation) optimises this by using gitolite access in batch mode. This does require a patch to be applied to gitolite at the moment. Since gitolite v3.6.16, my patch has been included in the release. In case you are on an older version, continue reading. If you are on at least v3.6.16, simply enabling the fastauth plugin should be enough.

I recommend patching the specific file and putting it in your local code:

1
2
3
4
5
6

GITSUNE=/path/to/gitsune/ # set this to the root of the gitsune repo
LOCAL_CODE="$(gitolite query-rc LOCAL_CODE)"; echo $? # if this fails, you have work to do.
mkdir -p "$LOCAL_CODE/commands"
curl -L https://codeberg.org/sitaramc/gitolite/raw/branch/master/src/commands/access -o "$LOCAL_CODE/commands/access"
chmod +x "$LOCAL_CODE/commands/access"
patch "$LOCAL_CODE/commands/acces" "$GITSUNE/gitolite-access.patch" # this does the heavy work

Afterwards, don't forget to add the fastauth plugin to the add_plugins config entry.

The other option, in case you are building gitolite from source, is to git apply the patch file on that. I use that method.