GitGres is a starting point for private reimplementations of GitHub optimizied for individual teams' agent needs. GitHub is a fantastic site for sharing code and it is likely how you're viewing this if you're a human. GitGres exists to solve for a few issues:
- Trading off cost for uptime. GitHub offers free code storage but less-than-stellar uptime. With GitGres, you have the flexibility to use a Postgres DBMS with tiered storage [1] to tune cost while maintaining uptime.
- Trading off latency for cost. GitHub puts you at the mercy of current system load. With GitGres, just choose your favorite Postgres cache [2].
- Trading off consistency for throughput. GitHub is a cloud service. If requests reach GitHub's servers out of order, bad things can happen. GitGres is a server backed by Postgres. It can run locally. It can run colocated with many agents. Consistency and throughput are fully tunable.
Everything - git objects, refs, packfiles, deltas, tokens, PRs, issues, comments, reviews, reactions, teams, orgs, events - lives in Postgres rows. The server holds nothing on disk.
Setup
# 1. Build (binaries land in ./target/release/{gitgres,git-remote-gitgres,gitgres-server}). cargo build --release --bins # 2. Have a Postgres reachable. e.g. export GITGRES_DB='host=localhost user=postgres dbname=gitgres' # 3. Apply the schema (idempotent). gitgres init # 4. Boot the server. The first --bootstrap-token mints an admin token tied # to user 'demo' that you can use to manage everything else through the API. gitgres serve --listen 0.0.0.0:8080 --bootstrap-token "$(openssl rand -hex 32)" # (For TLS:) gitgres serve --listen 0.0.0.0:8443 \ --tls /path/cert.pem /path/key.pem \ --bootstrap-token TOKEN
gitgres serve env vars:
| Var | Default | Purpose |
|---|---|---|
GITGRES_DB |
— | Postgres conn string if --db not given |
GITGRES_PUBLIC_URL |
https://gitgres.local |
Base URL the API returns in Repository.cloneUrl |
GITGRES_WORKERS |
8 |
HTTP worker threads |
GITGRES_GQL_LOG |
unset | If set, logs every GraphQL request body to stderr |
Usage
Plain git (smart HTTP, v1 + v2):
git clone http://gitgres.host/owner/repo.git git push http://demo:TOKEN@gitgres.host/owner/repo.git main
gh CLI:
# Print a hosts.yml entry, drop into ~/.config/gh/hosts.yml: gitgres gh-config --host gitgres.host --token TOKEN --user alice # Or pipe a token into gh: echo "TOKEN" | gh auth login --hostname gitgres.host --with-token gh pr create / list / view / merge / comment / close / diff gh issue create / list / view / comment / close gh repo create / view / clone / fork / list gh release create / list / view gh label create / list / edit / delete gh api /repos/owner/repo/... # the entire REST surface
Custom remote helper (alternative to smart HTTP, also works):
git clone "gitgres::host=db.local user=u dbname=gitgres#owner/repo"Limitations
Currently, GitGres doesn't support search, actions/workflows/runs/secrets, SSH transport, webhooks, HTTP/2, web UI.
Citations
[1] https://www.alibabacloud.com/help/en/polardb/polardb-for-postgresql/cold-data-archiving/