git-rest

git-rest

Lightweight REST API server for reading and writing files in a git repository. Auto-commits and pushes on writes, periodic pull keeps the local clone in sync.

Use Cases

• Expose a git repo to non-git clients (HTTP-only consumers, agents, K8s pods)
• Serve a vault/wiki/notes repo over HTTP without a database or web app
• Multi-instance deploys: one git-rest per repo, sharing nothing but the remote

Features

• File CRUD over HTTP — GET, POST, DELETE on /api/v1/files/{path}
• Glob-based file listing
• Auto-clone on startup if --git-remote-url is set and --repo is empty
• Auto-init local-only repos when no remote URL is configured
• Periodic git pull to stay in sync with the remote
• Auto git add + commit + push on every write/delete
• Optional SSH key + git author config
• Health and readiness endpoints (readiness reflects git status)
• Prometheus metrics on /metrics

Quick Start

# local repo, no remote (file CRUD only)
git-rest --repo /tmp/my-repo --listen :8080

# remote repo, auto-clone over SSH
git-rest \
  --repo /data \
  --listen :8080 \
  --git-remote-url git@github.com:owner/repo.git \
  --git-ssh-key /ssh/id_ed25519 \
  --git-user-name git-rest \
  --git-user-email git-rest@example.com \
  --pull-interval 30s

Configuration

All flags can be set as environment variables.

Build metadata (set via build flags):

Bootstrap Modes

git-rest decides what to do at startup based on --git-remote-url and the state of --repo:

Local-only mode (no remote) skips all push/pull operations — useful for testing or single-node deployments.

Documentation

• API Reference — full endpoint reference with curl examples
• Deployment Guide — Kubernetes + standalone setup
• Definition of Done — internal release criteria

License

BSD-2-Clause