basin

Small and lightweight git server for self hosting. Repositories are served over SSH and HTTPS, trees and logs and diffs and READMEs are rendered on the server rather than in the browser, and pull requests are handled without a working tree ever being checked out. The only JavaScript on the reading side is KaTeX, which is served only when a page contains mathematics.

Features

• Repos sit under ~user/name and can be public or unlisted or private. Each one takes up to three tags, and there is a /projects page that searches across all of them sorted by whoever pushed most recently
• Tree and blob and log and commit and refs views, plus a case insensitive search across file contents at any ref backed by git grep. Chroma does the highlighting and goldmark rendering the Markdown before bluemonday cleans it. Anything in $x$ or $$x$$ gets typeset in the browser
• The last commit shown against every tree entry comes out of one git log --name-only walk per directory instead of a separate process per file
• Profiles have a display name and a Markdown bio along with location and workplace and website, plus an avatar that you crop in the browser and the server then resamples down to a 256px PNG
• Forks and pull requests from either a branch or a fork. Discussion comments and inline review comments on any line of the diff are Markdown, review threads can be resolved and go to an outdated section when the line leaves the diff, merges take an editable message, and a request can be closed or reopened or brought up to date from its source at any point
• SSH signature verification. Sign with gpg.format ssh, register the same key in settings, and your commits start showing Verified ~you
• SSH keys and access tokens live in settings. HTTPS auth is plain basic auth with a token or your password
• Registration is invite only unless you say otherwise, and there is a failure counter per address covering login and register and password changes and HTTPS auth

Design

Every read of git data is a call out to the plumbing with a thirty second timeout, which in practice means ls-tree -l for trees and log with a NUL separated format for history and diff-tree -p --root -M for commit pages and cat-file for blobs. Nothing is cached anywhere and nothing is parsed out of packfiles in process, so a large repository costs exactly what git says it costs and the server itself holds no state between one request and the next.

When a pull request is opened or updated the source branch gets fetched into refs/pull/N/head of the target repository, and from that point on the diff and the commit list and the question of whether it merges cleanly all come from merge-base and diff and merge-tree --write-tree inside that single repo. The merge itself is commit-tree with both parents followed by update-ref carrying the old value it expects to find, so if someone pushes to the branch while you are clicking the button the merge simply fails rather than silently overwriting them. Conflicts are reported back to you and left for you to sort out locally.

SQLite comes from the modernc port, which is pure Go, so a CGO_ENABLED=0 build produces one static binary that will run anywhere there happens to be a system git next to it.

Install

CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o basin .
useradd -r -m -d /srv/basin -s /bin/sh git
install -m 755 basin /usr/local/bin/basin

[Service]
User=git
ExecStart=/usr/local/bin/basin -root /srv/basin serve -listen 127.0.0.1:3200 -host git.example.org
Restart=always
ProtectSystem=strict
ReadWritePaths=/srv/basin

Put a reverse proxy with TLS in front of it. The proxy needs to forward Host and X-Forwarded-Proto, and it should set X-Forwarded-For to the client address rather than appending to it because the rate limiter keys on the first value it finds there. Turn request buffering off and raise the body limit as well, otherwise larger pushes over HTTPS will be cut short.

Match User git
    AuthenticationMethods publickey
    AuthorizedKeysFile none
    AuthorizedKeysCommand /usr/local/bin/basin -root /srv/basin keys %u %h %t %k
    AuthorizedKeysCommandUser root
    PermitTTY no
    DisableForwarding yes

The keys command runs as root and opens the database read only and answers sshd with a forced command of basin shell <user>. That in turn runs as the login user, checks what SSH_ORIGINAL_COMMAND is actually asking for against the database, and then execs straight into git upload-pack or git receive-pack so nothing is left running afterwards.

sudo -u git basin -root /srv/basin invite

If you would rather let anyone sign up then serve -open skips the invite step entirely. basin user <name> creates an account from the command line with the password read from stdin, and -ssh-user changes the account name that appears in clone URLs if you did not call yours git.

Use

git clone https://git.example.org/~you/repo
git clone git@git.example.org:~you/repo

The .git suffix works but is not required. Pushing over SSH needs a key added under settings, while pushing over HTTPS takes a token or your password as the basic auth secret.

To send changes to something you do not own, fork it from the button beside the title and push a branch to your fork, then open a pull request from the pull requests tab and choose that branch as the source. The owner merges it from the sidebar when they are happy with it.

Limits

There are no squash or rebase merges, no collaborators beyond the single owner of a repo, and no disk quota of any kind. Blobs over 1 MiB are not rendered and anything over 64 MiB is not served raw either, while highlighting gives up past 256 KiB. Signature checking is SSH only for now, so commits signed with GPG show up as unverified.

Licence

MIT. KaTeX is MIT as well and Source Sans 3 is under the OFL, with both notices kept beside the files.