git http-backend

The thing your nginx/apache mounts to serve repos over HTTPS.

🎯 What & why

git http-backend is a CGI program that speaks the smart HTTP transport. Mount it behind nginx, Apache, or any CGI-capable web server to serve repos over HTTP(S).

🧠 Mental model

The web server handles TLS, auth, and URL routing; http-backend handles only the Git protocol on top. Authentication is the front-end's job — http-backend trusts REMOTE_USER and the AUTH_TYPE env vars the web server hands it.

🛠️ Synopsis

SetEnv GIT_PROJECT_ROOT /srv/git
SetEnv GIT_HTTP_EXPORT_ALL
ScriptAlias /git/ /usr/lib/git-core/git-http-backend/

# URL shape served:
#   GET  /<repo>.git/info/refs?service=git-upload-pack   (advertise refs)
#   POST /<repo>.git/git-upload-pack                     (fetch/clone)
#   POST /<repo>.git/git-receive-pack                    (push)

🎚️ Switches & options

Flag	What it does
`http.uploadpack`	Per-repo flag to allow fetch/clone over HTTP (default true)
`http.receivepack`	Per-repo flag to allow push over HTTP (default false — must enable)
`http.allowReachableSHA1InWant`	Permit clients to ask for any reachable SHA-1, not just advertised refs
`GIT_PROJECT_ROOT`	Env var: directory containing the repos to serve
`GIT_HTTP_EXPORT_ALL`	Env var: serve all repos, ignoring git-daemon-export-ok
`REMOTE_USER`	Env var set by the web server after auth — written into reflog for pushes
`http.receivepack=true without auth`	⚠️ Anonymous push — never deploy this on the open internet

💡 Use cases

Host private repos behind HTTPS with HTTP basic or OAuth at the proxy
Run a corporate Git server using existing nginx + LDAP infrastructure
Provide an HTTPS clone URL alongside SSH for users who cannot use port 22
Front a fleet of repos with caching, rate limiting, and TLS termination

🧪 Examples

Test the CGI directly with curl

curl -v 'http://127.0.0.1/git/repo.git/info/refs?service=git-upload-pack'

Enable push on a specific repo

git -C /srv/git/repo.git config http.receivepack true

nginx fastcgi snippet

fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend; fastcgi_param GIT_PROJECT_ROOT /srv/git; fastcgi_param GIT_HTTP_EXPORT_ALL '';

Clone over the local proxy

git clone http://127.0.0.1/git/repo.git

🎓 Recommendations

Terminate TLS at nginx/Apache and require auth there — http-backend itself does no authentication
Set http.receivepack=true only on repos that should accept push, and only behind authenticated routes
Watch the smart-protocol URL shape: /info/refs?service=... is mandatory; getting routing wrong yields 'dumb HTTP' fallback

🪤 Common pitfalls

Forgetting to set http.receivepack means push silently falls back to a 'service not enabled' error
Without REMOTE_USER, push reflog entries lose attribution — make sure the web server forwards it
Misconfigured CGI buffering breaks long-running clones; disable proxy buffering for the git endpoints

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.