go-git-server

go-git-server is an experimental web server that provides authentication and authorization for git repositories.

An attempt at a secure Git HTTP server implementation in Go that provides authentication and authorization, inspired by Gitolite.

Design

Initially go-git-server wraps the built-in git-http-backend CGI process. This is done to provide complete compatibility out of the box. In the future a native go backend could be created but there's no compelling story to re-write the backend.

Authentication is done using a token system with unique access IDs. Each token is associated with both an access ID (for internal use) and a friendly name (for human readability). Tokens are generated by the server with a fixed length of 32 bytes using cryptographically secure random numbers. The system supports different types of identities including users (uid:), service accounts (aid:), bots, and CI systems.

Authorization is implemented using casbin. The system provides role-based access control with predefined roles like admin, maintainers, and bots. Each role has specific permissions defined in the policy file.

Focus

The current focus is for a single user and CI user(s) and intends to become self hosted as soon as possible. The focus is to simplify ongoing maintance and hosting simplicity. It's specifically designed for running in kubernetes.

Why

Tools like gitea are great, but they require things like a DBMS. This increases hosting comlexity and maintenance especially for small teams or single user bases.

Features

Git HTTP backend wrapper with authentication
Token-based authentication
Role-based access control using Casbin
Git repository management
Configuration via Git (optional management repo)
Graceful fallback to default configuration when management repo is not found
Cgit support

Installation

# Clone the repository
git clone https://git.ofmax.li/go-git-server
cd go-git-server

# Build the binary
go build ./cmd/main.go

Usage

Start the server:

./main -r /path/to/repos -t tokens.csv -p policy.csv -m auth_model.ini

Generate Authentication Token

Currently the tokentool is not in the container nor is a binary built for it and available. You will have to build it yourself or use it like go run cmd/tokentool/main.go

./tokentool -generate -name username

This will: 1. Generate a new access ID and token 2. Create an entry in tokens.csv with the format: <access_id>,<friendly_name>,<hash> 3. Display the token that should be used for authentication

To list existing tokens:

./tokentool -list

The tokens.csv file format is:

access_id,friendly_name,hash

Special prefixes for friendly names: - uid: - Regular users (default if no prefix) - aid: - Special accounts with the following types: - bot+ - Bot accounts (e.g. bot+argo)

Configuration

Server Configuration (gitserver.yaml)

name: "go-git-server"
version: "v1alpha1"
basepath: ./repos
repos:
- name: myrepo
  public: false
  permissions:
  - role: maintainers
    mode: 1
  git_web_config:
    owner: username
    description: Repository description

The server will automatically use the repository directory path as the base path when using the default configuration if the management repository is not found.

Authentication Model (auth_model.ini)

The authentication model uses Casbin for role-based access control.

Token File (tokens.csv)

Format:

accessid,uid:username,hash

Development

Requirements: - Go 1.24+ - Git

Run tests:

just test