shithub

A 1:1 reverse-engineering of GitHub. AGPLv3. Without Copilot.

Honest status: very much a work in progress.

shithub is an attempt to recreate GitHub — the platform, the UI, the workflows — as faithfully as we can, as a self-hostable open-source forge. The goal is "you should barely notice you switched." We are nowhere near that yet. It will be some time before it looks and feels the way GitHub does. There is a lot of GitHub.

If you came here expecting drop-in parity, it's not ready for you. If you came here to watch (or help) one get built in the open, welcome.

What works today

The core forge loop works end-to-end against the codebase you're reading:

• Identity — email/password signup, email verification, password reset, TOTP 2FA + recovery codes, SSH keys, personal access tokens (scoped), sessions.
• Repositories — create, fork, archive, transfer, soft-delete with grace, rename with redirects, visibility toggles, branch protection (force-push / deletion / required reviews / required status checks), default-branch swap, topics, README/license/.gitignore templates.
• Git — bare repos on disk; HTTPS smart-HTTP push/pull (SSH service is planned but not shipped yet); pre/post-receive hook integration for size accounting and event emission.
• Code browsing — tree, blob (chroma syntax highlighting with light/dark themes), raw, blame, commit history, individual commit views, branch/tag listings, compare views, file finder.
• Issues & PRs — full CRUD on issues + comments + labels + milestones + assignees; pull requests with diff rendering, file-by-file review, line comments, reviews (approve/request-changes/comment), required-reviewer enforcement, status-check gates, three merge methods (merge / squash / rebase), conflict detection.
• Social — stars, watches with notification level, forks (clone-on-create), /explore, stargazer/watcher lists.
• Search — code search (path + content, tantivy-equivalent indexing in Postgres), repo search, user search, quick-search.
• Notifications — per-user inbox, email fan-out, watch-level routing, one-click HMAC-signed unsubscribe links, auto-subscribe on participation.
• Organizations & teams — create, member roles (member/owner), invitations, one-level team nesting, team grants on repos with max-of-sources policy aggregation.
• Repo settings — General (description, topics, features, merge methods), Access (collaborators + team grants), Branches (protection rules), Danger (rename/transfer/archive/visibility/delete).
• Webhooks — outbound delivery with HMAC-SHA256 signing, exponential backoff with jitter, auto-disable on persistent failure, SSRF defense (DNS resolve + IP block-list + dial-the-IP transport, no redirect-following), redelivery UI, ping events.

What doesn't work yet

Pulled directly from the sprint plan we're working through:

• SSH git service — HTTPS works; the SSH front-end is planned. Use HTTPS clone URLs for now.
• Actions / CI — there is no CI runner. Status checks are wired into PR gates so a future runner can publish into them.
• Packages, Pages, Projects, Releases, Gists — none of these surfaces exist yet.
• GraphQL API — only the internal HTTP surface exists. There is no public REST or GraphQL API.
• Activity feed — domain events are recorded but the activity-feed view isn't built.
• Admin / site-admin surface — there is no /admin UI. Operator tooling is via shithubd subcommands and SQL.
• Visual polish — most pages render correctly but do not look like GitHub yet. Spacing, typography, header/footer chrome, color tokens, octicon coverage, empty-state illustrations, focus states — all still drifting from Primer. Closing this gap is ongoing; expect rough edges page-to-page.
• Mobile / responsive — the current CSS is desktop-first. Small viewports work but aren't tuned.
• Deferred from completed sprints — every sprint spec lists "inbound deferrals" that landed and "outbound deferrals" that were pushed forward. See .docs/sprints/ for the running list.

Why

GitHub is a well-built platform. Microsoft's Copilot push has changed the product's character — particularly around how user code is treated as training data. shithub aims to recreate the parts that worked, on terms that make a self-hosted instance an honest equal to the SaaS experience, with AGPLv3 keeping any hosted variant open.

The "1:1" goal is intentional. There are plenty of git forges with their own UX vision; shithub deliberately doesn't try to be one of them. The closer the muscle-memory match, the lower the cost of switching.

Quickstart (development)

make dev          # hot-reload server on http://localhost:8080
make test         # run tests
make build        # build bin/shithubd
make ci           # full CI pipeline locally (mirrors GitHub Actions)
make dev-migrate  # apply DB migrations against $SHITHUB_DATABASE_URL

Requires:

• Go 1.22+ (developed against 1.26)
• PostgreSQL 13+
• A local MinIO (or any S3-compatible store) for the storage tests — make storage-up brings one up via docker-compose.
• golangci-lint, gofumpt, goimports, air, sqlc, goose (installed via go install per the Makefile or your package manager).

Copy .env.example to .env and fill in the database URL, session keys, and TOTP/webhook AEAD key.

Layout

cmd/shithubd/        # main entry: web, ssh, worker, migrate, storage, version
internal/auth/       # password, sessions, TOTP, PATs, SSH keys, policy/RBAC
internal/repos/      # repo lifecycle, git ops, branches, tags, diffs, forks
internal/issues/     # issues + comments + labels + milestones
internal/pulls/      # pull requests + reviews + merge orchestration
internal/orgs/       # orgs + teams + member roles + principals
internal/webhook/    # outbound delivery + SSRF defense + signing
internal/notif/      # inbox + email fan-out + watch-level routing
internal/search/     # code/repo/user search
internal/markdown/   # rendering + reference resolution (#N, @user, @org/team)
internal/web/        # HTTP handlers + html/template + middleware
internal/worker/     # Postgres-backed job queue + handlers
internal/migrationsfs/migrations/   # numbered SQL migrations (goose)
.docs/sprints/       # sprint specifications (S00–S49 + SR1)

Roadmap

The work is structured as 50 sprints (S00–S49, plus SR1 audit remediation). Roughly:

• S00–S04 — scaffolding, DB baseline, web shell, observability, storage abstractions ✅
• S05–S09 — identity (auth, 2FA, SSH keys, PATs, profiles) ✅
• S10–S20 — repos, git protocols, code browsing, branches/tags, hooks ✅ (SSH service deferred)
• S21–S25 — issues, pulls, reviews, status checks, markdown ✅
• S26–S29 — social, forks, search, notifications ✅
• S30–S33 — orgs, teams, repo settings, webhooks ✅ (current)
• S34–S40 — site admin, security hardening, federation, polish, accessibility, i18n
• S41–S49 — actions/CI, social feed, advanced search, GraphQL API, packages, pages, projects, releases, gists

See .docs/sprints/ for the per-sprint spec.

Contributing

See CONTRIBUTING.md. The project is in active rapid development — substantial PRs are best discussed in an issue first so we don't both write the same code. Small fixes, doc improvements, and bug reports are welcome any time.

Security

To report a security issue, see SECURITY.md. Please do not open a public issue for security reports.

License

AGPLv3. If you run a modified version as a network service, your users are entitled to the source.