WorkGit

Warning

This project is still in active development and should not be used in production environments.

A custom Git Smart HTTP(S) server written in Go, designed for everyone with built-in authentication, observability, and operational features.

Mostly, we started this project, because relaying on git-http-backend as the main Git server, may be not a great idea.

Quick Start

Installation

We suggest to deploy from Docker, as it uses Git and may messed up your config.

# Build
docker build -t workgit:latest .

# Run
docker run -d \
  -p 8080:8080 \
  -v /path/to/repos:/var/lib/workgit/repos \
  -v /path/to/config.yaml:/etc/workgit/config.yaml \
  workgit:latest

Or build from source:

git clone https://github.com/lluaguard/workgit
cd workgit
go build -o workgit ./cmd/workgit

Basic Usage

1. Create a configuration file config.yaml:

server:
  addr: ":8080"

storage:
  root: "./repos"
  defaultBranch: "main"

auth:
  anonymousRead: true
  tokens:
    - "your-secret-token"

log:
  level: "info"
  format: "json"

2. Start the server:

workgit serve --config config.yaml

3. Create a repository:

workgit repo create myproject.git

4. Use with Git:

# Clone (anonymous read if enabled)
git clone http://localhost:8080/myproject.git

# Push (requires authentication)
git remote add origin http://user:your-secret-token@localhost:8080/myproject.git
git push -u origin main

Configuration

Server

server:
  addr: ":8080"              # Listen address
  tls:
    enabled: true
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"

Storage

storage:
  root: "/var/lib/workgit/repos"  # Repository root directory
  autoInit: false                  # Auto-create repos on first access
  defaultBranch: "main"            # Default branch for new repos
  allowUnknownRepos: false         # Allow access to non-existent repos

Authentication

auth:
  anonymousRead: false  # Allow unauthenticated read access
  tokens:
    - "token1"
    - "token2"
  mtls:
    caFile: "/path/to/ca.pem"
    allowedSubjects:
      - "CN=client1"
      - "CN=client2"

Rate Limiting

limits:
  maxRequestMB: 100  # Maximum request body size in MB
  rateLimit:
    rps: 100         # Requests per second per IP
    burst: 200       # Burst capacity

CLI Commands

Server Management

# Start server
workgit serve --config config.yaml

# Override config with flags
workgit serve --addr :9000 --root /data/repos --anonymous-read

Repository Management

# Create repository
workgit repo create myrepo.git --default-branch main

# List repositories
workgit repo list

# Delete repository
workgit repo delete myrepo.git

# JSON output
workgit repo list --json

Authentication

WorkGit supports multiple authentication methods:

Bearer Token

git clone http://localhost:8080/repo.git
# When prompted:
# Username: <anything>
# Password: <your-token>

# Or in URL:
git clone http://user:token@localhost:8080/repo.git

Mutual TLS

Configure client certificates and CA:

auth:
  mtls:
    caFile: "/etc/workgit/ca.pem"
    allowedSubjects:
      - "CN=ci-server"

Then use git with client certificates:

git config --global http.sslCert /path/to/client.crt
git config --global http.sslKey /path/to/client.key
git clone https://git.example.com/repo.git

Observability

Metrics

Prometheus metrics available at /metrics:

• workgit_http_requests_total - HTTP request count by method/path/status
• workgit_http_request_duration_seconds - Request latency histogram
• workgit_git_operations_total - Git operations by service/operation/status
• workgit_git_operation_duration_seconds - Git operation latency
• workgit_active_connections - Current active connections

Health Checks

• GET /health/live - Liveness probe (always returns 200 if server is up)
• GET /health/ready - Readiness probe (checks storage access)

Logging

Structured logs with request tracing:

{
  "time": "2025-01-15T10:30:00Z",
  "level": "info",
  "msg": "request",
  "request_id": "1234567890",
  "method": "POST",
  "path": "/repo.git/git-receive-pack",
  "status": 200,
  "duration_ms": 1234,
  "remote": "10.0.1.5:54321"
}

Deployment

Kubernetes (not tested)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: workgit
spec:
  replicas: 3
  selector:
    matchLabels:
      app: workgit
  template:
    metadata:
      labels:
        app: workgit
    spec:
      containers:
      - name: workgit
        image: workgit:latest
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: repos
          mountPath: /var/lib/workgit/repos
        - name: config
          mountPath: /etc/workgit
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080
      volumes:
      - name: repos
        persistentVolumeClaim:
          claimName: workgit-repos
      - name: config
        configMap:
          name: workgit-config

Testing

Run unit tests:

go test ./...

Run tests with coverage:

go test -cover ./...

Run integration tests with real Git:

# Requires git binary in PATH
go test -tags=integration ./internal/git/...

Run fuzz tests:

go test -fuzz=FuzzPktLine ./internal/git

Environment Variables

All configuration can be overridden via environment variables:

• WORKGIT_CONFIG - Config file path
• WORKGIT_ADDR - Server address
• WORKGIT_STORAGE_ROOT - Repository root
• WORKGIT_TLS_CERT - TLS certificate file
• WORKGIT_TLS_KEY - TLS key file
• WORKGIT_ANONYMOUS_READ - Allow anonymous read (true/false)
• WORKGIT_AUTO_INIT - Auto-initialize repos (true/false)

SHA-256 Object Format

WorkGit defaults to SHA-1 but supports SHA-256 repositories. To use SHA-256:

# Create SHA-256 repository
git init --object-format=sha256 --bare /path/to/repo.git

# WorkGit will automatically detect and advertise object-format=sha256

Note: Ensure all clients support SHA-256 (Git 2.29+).

Contributing

Contributions are welcome! Please:

1. Run tests: go test ./...
2. Run linters: go vet ./... and staticcheck ./...
3. Format code: gofmt -s -w .
4. Update documentation for new features

License

GPLv3 License - see LICENSE file for details.

Support

• Issues: https://github.com/lluaguard/workgit/issues
• Documentation: https://github.com/lluaguard/workgit/wiki