git-rest

git-rest

Lightweight REST API server for reading and writing files in a git repository. A write is written and staged; a background flusher commits and pushes a burst of writes as one commit, and a periodic pull keeps the local clone in sync.

Where this fits in the bigger picture

This service is the vault writer in the bborbe task / agent pipeline. agent's task/controller calls git-rest over HTTP to create / update / delete the markdown task files that materialize Kafka task.CreateCommand events into an Obsidian vault git remote.

git-rest itself knows nothing about tasks, vaults, or Kafka — it's a generic HTTP-over-git CRUD service. Any consumer wanting an HTTP write-path into a git repo can use it.

Full system map: recurring-task-creator/docs/system-map.md.

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}
• Claim refs under refs/claims/ over HTTP — GET /api/v1/refs, PUT and DELETE on /api/v1/refs/claims/{key} with an origin-enforced compare-and-swap lease (a lost race is 409 and must not be retried)
• 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
• Coalesced writes — git add + commit + push runs in a background flusher once per window (default 30s quiet, 120s ceiling), not inside the request; deletes stay synchronous
• Optional SSH key + git author config
• Health and readiness endpoints (readiness reflects whether the served repository path is readable)
• 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