flatgit

A static Git web generator with webhook-driven updates and an optional built-in file server.

The main goal for this projects is to make bots and agents's life easier. Also to relief the stress on them crawling the forge platform interfaces.

Each repository have a manifest.json that lists all available navigation paths.

Demo

Install

via helm

helm show values ./resources/flatgit.chart/ > values.yaml
edit values.yaml
helm upgrade --install -n <NAMESPACE> <RELEASE_NAME> ./resources/flatgit.chart/ -f values.yaml

Philosophy

Git repo in, static browsable site out.

webhook -> git clone/fetch --mirror -> render HTML + JSON -> serve static files

It currently shells out to the real git binary.

Since Git already knows how to deal with packed refs, tags, bare repositories, weird histories, and future compatibility. The main focus is on rendering.

HTML should be served by proper http server if possible. The built-in server is fine but basic.

Current status

• flatgit render one-shot renderer
• flatgit serve static file server
• flatgit daemon webhook + render workers + static serving
• mirror clone/fetch using git clone --mirror and git remote update --prune
• simple HTML pages:
  • summary
  • refs
  • log
  • tree listing
  • blob view
  • commit patch view
• JSON files:
  • flatgit.json
  • refs.json
  • commits.json
  • tree.json
  • commit/<sha>.json
• Gitea/GitHub-style webhook endpoints:
  • POST /webhook/gitea
  • POST /webhook/github

Build

make clean build

Config

See examples/tinyproxy.json:

{
  "addr": ":8080",
  "data_dir": "/var/lib/flatgit",
  "webhook": {
    "secret": "change-me"
  },
  "git": {
    "command": "git",
    "clone_timeout": "2m",
    "fetch_timeout": "2m"
  },
  "render": {
    "workers": 2,
    "max_commits": 500
  },
  "repos": [
    {
      "owner": "penguin",
      "name": "test-repo",
      "url": "http://gitea-http.gitea.svc.cluster.local:3000/penguin/test-repo.git",
      "default_branch": "main"
    }
  ]
}

Derived paths:

/var/lib/flatgit/repos/penguin_test-repo.git
/var/lib/flatgit/www/penguin_test-repo

Commands

Render all configured repos:

flatgit render -c examples/flatgit.json

Render one repo:

flatgit render -c examples/flatgit.json -repo penguin_test-repo

Serve an already-rendered web root:

flatgit serve -root /var/lib/flatgit/www -addr :8080

Run the daemon:

flatgit daemon -c examples/flatgit.json

The daemon serves:

/                       static web root
/healthz                health check
/webhook/gitea          Gitea webhook endpoint
/webhook/github         GitHub webhook endpoint

Webhook signature

If webhook.secret is non-empty, the handler accepts either:

• X-Hub-Signature-256: sha256=<hex-hmac>
• X-Gitea-Signature: <hex-hmac>

The HMAC is SHA-256 over the raw request body.

TODO

• Add README rendering
• Add syntax highlighting, probably with a tiny vendored/highlight-free first pass
• Improve branch/tag URL escaping
• Render per-branch trees instead of only the default branch
• Add archive links
• Add repo index page at the web-root
• Add tests using temporary local Git repos