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.
# 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 |
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"
Currently, GitGres doesn’t support search, actions/workflows/runs/secrets, SSH transport, webhooks, HTTP/2, web UI.
[1] https://www.alibabacloud.com/help/en/polardb/polardb-for-postgresql/cold-data-archiving/
