githome

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: Apache-2.0

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.

Install

Tagged releases ship as static binaries for Linux, macOS, Windows and the BSDs, as Linux packages (deb, rpm, apk), and as a multi-arch container image. The common paths:

brew install tamnd/tap/githome                       # macOS
docker pull ghcr.io/tamnd/githome:latest             # container
go install github.com/tamnd/githome/cmd/githome@latest  # from source

INSTALL.md covers every method (Homebrew, Scoop, winget, deb, rpm, apk, the AUR, Nix, Docker, prebuilt archives) and the server configuration.

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

Path Synopsis
api
graphql
Package graphql implements Githome's GraphQL API v4.
 Package graphql implements Githome's GraphQL API v4.
graphql/dataloader
Package dataloader provides a generic per-request batch loader.
 Package dataloader provides a generic per-request batch loader.
graphql/generated
rest
Package rest implements Githome's REST API v3.
 Package rest implements Githome's REST API v3.
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.
githome-realworld-ingest command
Command githome-realworld-ingest runs the two-stage real-world corpus pipeline: Stage A exports public repository metadata and git history into a pinned, normalized snapshot, and Stage B seeds that snapshot into a target store.
 Command githome-realworld-ingest runs the two-stage real-world corpus pipeline: Stage A exports public repository metadata and git history into a pinned, normalized snapshot, and Stage B seeds that snapshot into a target store.
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.
Package domain holds Githome's business logic and value objects.
 Package domain holds Githome's business logic and value objects.
Package etag computes deterministic HTTP entity tags for Githome responses.
 Package etag computes deterministic HTTP entity tags for Githome responses.
fe
Package fe mounts the Githome web front: the human-facing, server-rendered HTML surface that sits beside the REST and GraphQL APIs in the same binary.
 Package fe mounts the Githome web front: the human-facing, server-rendered HTML surface that sits beside the REST and GraphQL APIs in the same binary.
assets
Package assets owns the Githome web front's built static assets: the content-hashed CSS and JS bundles, the manifest that maps a logical name to its hashed file, and the Octicon-equivalent icon registry the render layer inlines.
 Package assets owns the Githome web front's built static assets: the content-hashed CSS and JS bundles, the manifest that maps a logical name to its hashed file, and the Octicon-equivalent icon registry the render layer inlines.
assets/build command
Command build compiles the Githome web front assets.
 Command build compiles the Githome web front assets.
render
Package render is the Githome web front's html/template engine.
 Package render is the Githome web front's html/template engine.
route
Package route holds the Githome web front's URL-space rules: the reserved top-level names that a user or organization login may not take, and the ref-versus-path split that the tree and blob URLs need.
 Package route holds the Githome web front's URL-space rules: the reserved top-level names that a user or organization login may not take, and the ref-versus-path split that the tree and blob URLs need.
view
Package view builds the view models the render layer turns into HTML.
 Package view builds the view models the render layer turns into HTML.
web/checks
Package checks holds the Githome web front's commit-checks surface: the page at /{owner}/{repo}/checks/{ref} that shows the status-check rollup for a ref, its check-run rows, and its commit-status rows.
 Package checks holds the Githome web front's commit-checks surface: the page at /{owner}/{repo}/checks/{ref} that shows the status-check rollup for a ref, its check-run rows, and its commit-status rows.
web/issues
Package issues holds the Githome web front's issues handlers: the index with its search-and-filter bar, the detail page with its comment timeline and sidebar, the comment composer, the reactions, and the new-issue form.
 Package issues holds the Githome web front's issues handlers: the index with its search-and-filter bar, the detail page with its comment timeline and sidebar, the comment composer, the reactions, and the new-issue form.
web/profile
Package profile holds the Githome web front's profile handlers: the user and organization overview at /{owner} and its repositories tab.
 Package profile holds the Githome web front's profile handlers: the user and organization overview at /{owner} and its repositories tab.
web/pulls
Package pulls holds the Githome web front's pull-request handlers: the index with its state tabs, the PR shell the four tabs hang off, the Conversation timeline, the Commits tab, the read-only Files-changed diff, and the merge box with its poll fragment and merge mutation.
 Package pulls holds the Githome web front's pull-request handlers: the index with its state tabs, the PR shell the four tabs hang off, the Conversation timeline, the Commits tab, the read-only Files-changed diff, and the merge box with its poll fragment and merge mutation.
web/repo
Package repo holds the Githome web front's code-browsing handlers: the repo home, the tree and blob views, the raw byte view, commit history, the branch and tag overviews, and the file finder.
 Package repo holds the Githome web front's code-browsing handlers: the repo home, the tree and blob views, the raw byte view, commit history, the branch and tag overviews, and the file finder.
web/reposettings
Package reposettings holds the Githome web front's repository settings handlers.
 Package reposettings holds the Githome web front's repository settings handlers.
web/search
Package search holds the Githome web front's search surface: the global /search page and the in-repo /{owner}/{repo}/search page.
 Package search holds the Githome web front's search surface: the global /search page and the in-repo /{owner}/{repo}/search page.
web/settings
Package settings holds the Githome web front's account settings handlers.
 Package settings holds the Githome web front's account settings handlers.
webmw
Package webmw holds the Githome web front's middleware: the signed session cookie that resolves the viewer, the color-mode cookie, the CSRF guard, the one-shot flash cookie, and the panic recovery that renders the HTML error page.
 Package webmw holds the Githome web front's middleware: the signed session cookie that resolves the viewer, the color-mode cookie, the CSRF guard, the one-shot flash cookie, and the panic recovery that renders the HTML error page.
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.
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.
Package jsondiff makes "100% compatible with GitHub" mechanical.
 Package jsondiff makes "100% compatible with GitHub" mechanical.
Package markup renders GitHub Flavored Markdown to sanitized, trusted HTML and highlights source code, for BOTH the web frontend and the REST text/html media type.
 Package markup renders GitHub Flavored Markdown to sanitized, trusted HTML and highlights source code, for BOTH the web frontend and the REST text/html media type.
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.
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.
Package realworld is the real-world ingest subsystem: it exports the public metadata and git history of a handful of the largest GitHub-native repositories into a pinned, normalized corpus, then seeds that corpus into a Githome instance so the read, write, search, git, and event paths can be exercised at a scale the small development fixture never reaches.
 Package realworld is the real-world ingest subsystem: it exports the public metadata and git history of a handful of the largest GitHub-native repositories into a pinned, normalized corpus, then seeds that corpus into a Githome instance so the read, write, search, git, and event paths can be exercised at a scale the small development fixture never reaches.
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.
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.
Package webhook delivers a repository's recorded events to its registered hooks.
 Package webhook delivers a repository's recorded events to its registered hooks.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.