A 1:1 reverse-engineering of GitHub. AGPLv3. Without Copilot.
--- **Status: v0.1.0 launched — early days. Honest about WIP areas.** 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 not there yet. The core forge loop works end-to-end (see "What works today"); large surfaces such as GraphQL, Packages, Pages, Projects, Releases, and Gists are still explicitly outside the current shipped surface. The hosted instance is at **[shithub.sh](https://shithub.sh)**. The project's own source has migrated here from GitHub; this GitHub repo is a one-way mirror for the first 90 days post-launch as a recovery surface. If you came here expecting drop-in parity with everything GitHub does, you'll find specific gaps. If you came here for an honest, AI-free, self-hostable forge, this is for you. ## 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 and SSH push/pull (sshd `Match User git` dispatches to shithubd via `AuthorizedKeysCommand`); 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), follows for users/orgs, Home/Explore feeds, trending repositories/developers, stargazer/watcher/follower 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. - **Actions / CI v1** — `.shithub/workflows` parser, push/PR/schedule/dispatch triggers, per-repo/org secrets and variables, runner registration, single-use job JWTs, scoped checkout, containerized `run:` steps, live logs, cancel/re-run, retention, check-run sync, Atom feed, and monitoring. v1 intentionally supports `actions/checkout@v4` plus `run:` steps, not arbitrary marketplace actions. ## What doesn't work yet Pulled directly from the sprint plan we're working through: - **Actions marketplace parity** — shithub Actions does not execute arbitrary `uses:` steps, matrix builds, service containers, composite actions, or hosted runner images. The project's full CI remains on GitHub Actions until the first-party runner image/Nix toolchain can run it without marketplace setup actions; `.shithub/workflows/checkout-canary.yml` is the current dogfood canary. - **Packages, Pages, Projects, Releases, Gists** — none of these surfaces exist yet. - **GraphQL API** — a documented REST API ships under `/api/v1` (see `docs/public/api/`); a GraphQL surface is not yet planned. - **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) ```sh 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 (HTTPS + SSH), code browsing, branches/tags, hooks ✅ - **S21–S25** — issues, pulls, reviews, status checks, markdown ✅ - **S26–S29** — social, forks, search, notifications ✅ - **S30–S33** — orgs, teams, repo settings, webhooks ✅ - **S34** — site admin (`/admin/*`) ✅ - **S41** — actions/CI v1 ✅ - **S35–S40, S42–S49** — security hardening, federation, polish, accessibility, i18n; social feed, advanced search, GraphQL API, packages, pages, projects, releases, gists See `.docs/sprints/` for the per-sprint spec. ## Contributing See [CONTRIBUTING.md](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](SECURITY.md). Please do not open a public issue for security reports. ## License [AGPLv3](LICENSE). If you run a modified version as a network service, your users are entitled to the source.