Gittlz

A Git server for the laziest of us. Write and test your Git utilities without any hassle.

• Gittlz
  • Do you need Gittlz?
  • Prerequisites
  • Usage
  • Examples
    • Setting up a cloneable repo over HTTP with basic auth
    • Using Gittlz in GitHub Actions
  • Authentication
    • SSH password authentication
    • SSH key authentication
    • HTTP URL authentication
    • HTTP basic authentication
  • Containerless
  • Architecture

Do you need Gittlz?

If all you need is a no-auth Git remote (not necessarily a server), consider trying Git's Local protocol first.

Gittlz is meant to work in place of a live Git host for development purposes, and not to act as a production server in any form. If that's what you were looking for, try Gitea, Gogs, OneDev, or Soft Serve, among the many projects floating around.

This will likely be repeated several times throughout this documentation: Do not use Gittlz as a production Git server.

Prerequisites

Have the following software installed before using Gittlz:

• Docker (to run the container)
• Go v1.19+ (to build/install the CLI)

Usage

Gittlz requires no configuration by default - just point a Git client at it and get started:

docker run --rm -it -p 6177:6177 -p 9418:9418 karashiiro/gittlz:latest

If you want to use a persistent directory for repositories, mount it to /srv/git:

docker run --rm -it -v /path/to/repos:/srv/git:rw -p 6177:6177 -p 9418:9418 karashiiro/gittlz:latest

Repositories should be bare repositories on the server. The Gittlz CLI abstracts away this setup process:

CGO_ENABLED=0 go install github.com/karashiiro/gittlz@v0.3.0
gittlz create-repo repo

Then, you can clone repositories from a Git client outside the container:

git clone git://localhost/repo.git

And that's it! Enjoy your Gittlz.

The Gittlz Docker image makes this setup process nearly as simple as it can be. The image is based on Alpine Linux, but it includes a full Git installation, which can be used to manually perform operations inside the container. sh is available as a basic shell for manual repository setup, if needed.

Examples

These are some common workflows using Gittlz, provided with minimal commentary and as few assumptions as possible. These examples use Git Bash, and may need to be adjusted to work in other shells. The Gittlz CLI is assumed to be installed before running these examples.

Setting up a cloneable repo over HTTP with basic auth

# Create the Gittlz instance with non-persistent data, and detach it from the shell
docker run --rm -it -d --name=gittlz -p 6177:6177 -p 80:80 karashiiro/gittlz:latest gittlz serve --protocol=http --username=gitt --password=lz
# Create a repository on the server called "example.git"
gittlz create-repo example
# Base64-encode the username:password pair
echo -n "gitt:lz" | base64 # Z2l0dDpseg==
# Clone the repository
git -c http.extraHeader="Authorization: Basic Z2l0dDpseg==" clone http://localhost:80/example.git
# (Optional) Delete the Gittlz instance, and all of the data on it
docker kill gittlz

Using Gittlz in GitHub Actions

An example workflow file is available here. Gittlz can be used via service containers on Linux runners. Using Gittlz on other runners requires containerless setup.

Authentication

Gittlz comes preconfigured with no authentication whatsoever. All of the optional authentication methods provided are intentionally insecure - Gittlz favors convenience over security where possible.

Do not use Gittlz as a production Git server.

The following forms of authentication are configurable:

• SSH password authentication
• SSH key authentication
• HTTP URL authentication
• HTTP basic authentication

This covers the majority of authentication schemes used by Git hosting providers.

SSH password authentication

Start the server with a command override, replacing the port mapping and password options as needed:

docker run --rm -it -p 6177:6177 -p 22:22 karashiiro/gittlz:latest gittlz serve --protocol=ssh --password=password

Then, clone repositories by providing the password interactively:

git clone ssh://localhost/repo.git
# Cloning into 'repo'...
# you@localhost's password: password

It is not possible to use this authentication method non-interactively.

SSH key authentication

Note that Gittlz will not validate the SSH key used to access the server. This is intentional, as key configuration has little to do with a Git server's public interface. That said, if your use case requires SSH key auth failures, open an issue describing your intended workflow.

Start the server with a command override, replacing the port mapping as needed:

docker run --rm -it -p 6177:6177 -p 22:22 karashiiro/gittlz:latest gittlz serve --protocol=ssh

Then, clone repositories with a Git client:

git clone ssh://localhost/repo.git

You may also want to override your Git client's SSH command to avoid host key verification errors. This is done by setting the GIT_SSH_COMMAND environment variable, which is shell-specific. In sh-like shells, this can simply be prepended to the command:

GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no" git clone ssh://localhost/repo.git

HTTP URL authentication

See HTTP basic authentication. The same setup applies, but the username and password can be embedded in the URL:

git clone http://gitt:lz@localhost/repo.git

This authentication scheme is both insecure and deprecated by many clients. Some Git clients will even silently strip the credentials out of the URL. cURL automatically converts it into an Authorization header.

Be prepared to debug issues yourself.

HTTP basic authentication

Start the server with a command override, replacing the port mapping, username, and password options as needed:

docker run --rm -it -p 6177:6177 -p 80:80 karashiiro/gittlz:latest gittlz serve --protocol=http --username=gitt --password=lz

Then, make sure to base64-encode the username and password somewhere locally. Most operating systems and shells have a means of doing this. In Powershell, for example:

$gittlzAuth = "gitt:lz"
$B64gittlzAuth = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($gittlzAuth))

Finally, add the http.extraHeader option to all of your Git commands:

git -c http.extraHeader="Authorization: Basic $B64gittlzAuth" clone http://localhost/repo.git

Containerless

The Gittlz container attempts to abstract configuration as much as possible, without sacrificing maintainability or debuggability. However, Gittlz is also just a CLI application, and can be built and run in other environments.

Building Gittlz from sources is simple, just disable cgo (optional) and install it like any other Go application. In sh-like shells, this is done as follows:

CGO_ENABLED=0 go install github.com/karashiiro/gittlz@v0.3.0

Gittlz has runtime dependencies on the standard git toolkit and git-http-backend. git-http-backend is a CGI script sometimes offered as part of a separate git-daemon package. For Windows users, Git for Windows includes everything needed in a single installer.

Refer to the --help commands such as gittlz --help and gittlz serve --help for configuration options.

Architecture

Git's server functionality is mostly usable out of the box, and the official handbook even dedicates an entire chapter to describing how to configure and use it. However, that's more configuration than anyone should want to do if they only want a disposable HTTP or SSH Git server, and don't care about security at all.

With this being the case, Gittlz is just a very thin wrapper around Git itself, with the exception of the handling for the SSH protocol. Each protocol has a different strategy used to wrap it.

Protocol	Strategy
Git	git daemon is launched as a subprocess. That's it.
HTTP	net/http/cgi (yes, that's part of the Go standard library) is used to interface with git-http-backend. Gittlz adds some authentication middleware to simulate a typical managed Git provider.
SSH	charmbracelet/wish is used to set up a simple SSH server in front of Git. Gittlz's implementation is almost an exact copy of Wish's Git example.

The serve command is used to select which protocol is used at runtime.

Finally, a control API is put on top for simpler repository creation within the container.