githome

module

v0.1.0 Latest Latest Go to latest Published: Jun 5, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tamnd/githome

Links

Open Source Insights

README ¶

Githome

Githome is a self-hosted software forge that speaks GitHub. The goal is narrow and uncompromising: an unmodified gh, an unmodified git, and any client that talks to the GitHub REST or GraphQL API should work against a Githome server the same way they work against github.com, byte for byte where it matters.

That means the compatibility target is not "GitHub-like". It is GitHub:

REST API v3 under /api/v3, with the same JSON shapes, the same error envelopes, the same headers (Link pagination, ETag, the rate-limit family, X-GitHub-Request-Id, X-GitHub-Api-Version).
GraphQL API v4 under /api/graphql, with a schema that matches field for field, Relay-style connections, and the node/databaseId/id triple.
The gh CLI, unmodified, pointed at a Githome host through GH_HOST. If a flow works on github.com it works here, including --json field selection and --paginate.
Git transport, smart-HTTP and SSH, so git clone and git push go straight to the server.

Status

Early and honest about it. Githome is being built milestone by milestone, and each milestone lands as its own pull request with a runnable acceptance gate before the next one starts. The roadmap is:

Milestone	Theme	Lands
M0	Foundations: config, store, migrations, the REST envelope, `/meta`, `/rate_limit`, health	first
M1	Authentication: tokens, OAuth device + web flow, `gh auth login`
M2	Repositories and git read: clone, browse contents and trees
M3	Git write: push, refs, the post-receive sync
M4	Issues
M5	Pull requests
M6	Code review
M7	Webhooks and events
M8	Hardening and parity: search, conditional requests, conformance

A milestone is only "done" when its acceptance gate is green in CI and every new endpoint has a recorded fixture and a passing contract test. The mechanical definition of done lives in the test suite: real gh and real git driving the server, and a JSON differ that compares Githome's output against recorded github.com responses field for field.

Design in one screen

A single Go binary, githome, plus a githome-migrate helper.
Postgres is the primary datastore; SQLite (pure Go, no cgo) is supported for small and single-node deployments. The same migrations run on both.
Git access is hybrid: go-git for cheap reads, the git binary for transport, merge, and diff.
One rule keeps the two API surfaces from drifting apart: the REST and GraphQL layers never touch the store or git directly. Both go through the domain layer for data and a presenter layer for rendering, so neither surface can diverge from the other or from GitHub.

There are no Go internal/ directories in this project on purpose; boundaries are enforced by the single-writer domain layer and by lint, not by the package system.

Build

Requires Go 1.26 or newer and a git binary on PATH.

make build      # build ./bin/githome and ./bin/githome-migrate
make test       # run the test suite (SQLite by default)
make lint       # golangci-lint v2

Running the server and pointing gh at it is documented as the milestones that serve those flows land.

License

Apache License 2.0. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
graphql Package graphql implements Githome's GraphQL API v4.	Package graphql implements Githome's GraphQL API v4.
graphql/generated
rest Package rest implements Githome's REST API v3.	Package rest implements Githome's REST API v3.
auth Package auth turns a raw HTTP credential into a normalized Actor and decides what that actor may do.	Package auth turns a raw HTTP credential into a normalized Actor and decides what that actor may do.
cmd
githome command Command githome runs the Githome server.	Command githome runs the Githome server.
githome-conform command Command githome-conform certifies a running Githome instance against the compatibility matrix: it points at a base URL with an auth token and a target repository, runs the section-3 surface (repository read, conditional requests, issue listing and pagination, the search endpoints, and GraphQL introspection plus a connection query), and prints a pass/fail report.	Command githome-conform certifies a running Githome instance against the compatibility matrix: it points at a base URL with an auth token and a target repository, runs the section-3 surface (repository read, conditional requests, issue listing and pagination, the search endpoints, and GraphQL introspection plus a connection query), and prints a pass/fail report.
githome-migrate command Command githome-migrate applies or rolls back Githome's database migrations.	Command githome-migrate applies or rolls back Githome's database migrations.
config Package config loads and validates Githome's runtime configuration from the environment (with an optional file overlay) into a single immutable Config.	Package config loads and validates Githome's runtime configuration from the environment (with an optional file overlay) into a single immutable Config.
domain Package domain holds Githome's business logic and value objects.	Package domain holds Githome's business logic and value objects.
etag Package etag computes deterministic HTTP entity tags for Githome responses.	Package etag computes deterministic HTTP entity tags for Githome responses.
git Package git is Githome's read access to the bare repositories on disk.	Package git is Githome's read access to the bare repositories on disk.
gittransport Package gittransport serves git clone and fetch over the Git Smart HTTP protocol.	Package gittransport serves git clone and fetch over the Git Smart HTTP protocol.
jsondiff Package jsondiff makes "100% compatible with GitHub" mechanical.	Package jsondiff makes "100% compatible with GitHub" mechanical.
nodeid Package nodeid encodes and decodes the opaque identifiers Githome uses for the GraphQL `id` field and the REST `node_id` field.	Package nodeid encodes and decodes the opaque identifiers Githome uses for the GraphQL `id` field and the REST `node_id` field.
presenter Package presenter renders domain values into the exact wire shapes GitHub emits.	Package presenter renders domain values into the exact wire shapes GitHub emits.
gqlmodel Package gqlmodel holds the hand-written Go types that back Githome's GraphQL object types and scalars.	Package gqlmodel holds the hand-written Go types that back Githome's GraphQL object types and scalars.
restmodel Package restmodel holds the exact JSON wire structs Githome serves on the REST API.	Package restmodel holds the exact JSON wire structs Githome serves on the REST API.
search Package search parses GitHub's search query mini-language into the structured form the domain resolves and the store filters on.	Package search parses GitHub's search query mini-language into the structured form the domain resolves and the store filters on.
store Package store is the single entry point to Githome's metadata database.	Package store is the single entry point to Githome's metadata database.
migrations Package migrations holds Githome's embedded SQL schema migrations and exposes them as a read-only filesystem for the store's migration runner.	Package migrations holds Githome's embedded SQL schema migrations and exposes them as a read-only filesystem for the store's migration runner.
webhook Package webhook delivers a repository's recorded events to its registered hooks.	Package webhook delivers a repository's recorded events to its registered hooks.
worker Package worker is the background job queue: the enqueue API job producers submit through, and (from a later milestone) the claim-and-run loop that drains it.	Package worker is the background job queue: the enqueue API job producers submit through, and (from a later milestone) the claim-and-run loop that drains it.