GOLFS is a stateless Git LFS server for GitHub.com repositories backed by private Hetzner Object Storage through its S3-compatible API. It authenticates GitHub App users, authorizes repository access, implements the Git LFS Batch and Verify APIs, and returns direct presigned S3 actions. Object bytes never pass through GOLFS.
GOLFS supports the Git LFS Basic Transfer protocol with SHA-256 objects up to 5,000,000,000 bytes. It deliberately excludes a database, multipart uploads, locking, garbage collection, object deletion, administration commands, and automatic fork provisioning.
Start with Installation, then Configuration and GitHub App and GCM setup to deploy the server and connect a client.
To understand the system, read Architecture, Security, and Language and foundations. For ongoing work, use Operations, Testing, and Release process. The security policy covers private reporting and supported versions.
- A Git LFS client sends Basic credentials to the repository-specific Batch endpoint. The password is a GitHub App user access token.
- GOLFS proves that the configured App is installed on the repository, that GitHub returned an operator-allowlisted installation ID, that the user token can access that installation, and that the user has the needed repository permission.
- GOLFS resolves GitHub's canonical numeric repository ID and checks whether the expected S3 object exists with the requested size.
- GOLFS returns a presigned S3 PUT or GET action. Uploads also receive a GOLFS Verify action.
- Hetzner enforces the signed SHA-256 payload hash and conditional object creation during upload. GOLFS confirms object existence and size during Verify and every download Batch.
Object keys have the stable form:
github/{numeric-repository-id}/objects/{first-two-oid-characters}/{next-two-oid-characters}/{full-sha256-oid}
The public listener serves:
POST /github.com/{owner}/{repository}/info/lfs/objects/batch
POST /github.com/{owner}/{repository}/info/lfs/objects/verify
The cluster-internal operations listener serves:
GET /healthz
GET /readyz
GET /metrics
There are no object proxy or redirect routes. See Architecture, configuration, and operations for the complete contract.
Create and install the GitHub App, then configure GCM 2.9.0 or later using the exact commands in GitHub App and GCM setup. Set the repository's LFS URL:
git config --local lfs.url "https://lfs.example.com/github.com/OWNER/REPOSITORY/info/lfs"No GitHub App client secret is distributed.
Go 1.27.0 is required:
go test ./...
go vet ./...
go build ./cmd/golfsSee Testing for the current automated coverage, CI checks, and manual external-service gates. The docs README covers website development.
A non-root container and Helm chart are included. The chart exposes the public and operations listeners through separate Services and routes only the public Service through the optional Gateway API resources. Follow Installation for prerequisites, HTTPS routing, and acceptance checks; use the chart README for Secret and chart installation details.
GOLFS is an independent implementation licensed under Apache-2.0. Its protocol and architecture were informed by public Git LFS specifications and an existing Git LFS server, but its source and Git history are independent.