krz/gitbay

A CLI-first git forge.

cli forge git self-hosted

https://gitbay.org

Wiki: Roadmap

Roadmap

gitbay roadmap

Status and direction as of 2026-08-24. Issue numbers reference this repository's tracker; this file is the narrative, the tracker is the truth.

Where things stand

Everything in the original plan is built, tested end-to-end against real git/ssh/sshd/gpg, and running in production at gitbay.org: the SSH control plane (usable from bare OpenSSH, enforced by test), git over SSH/HTTPS/git://, signature verification with six states and epoch caching, protected branches and require_signed_commits (push-time and merge-time), issues, merge requests with four merge strategies, orgs with membership-derived access, rename/transfer, repo import, invite and open registration with SMTP verification, ACME TLS, the read-only and accounts web modes, the JSON API fronting the whole command registry, signed webhooks with retries and dead-lettering, restore-tested backups, the gitbay CLI, and docs. The instance hosts 65 repositories including this one, and its own development already runs through its issues and merge requests.

What it is today: an excellent forge for its author and for CLI-native individuals. What it is not yet: a forge a GitHub-habituated team would stay on, or a project outsiders can easily run themselves.

Phase 1 — collaboration credibility [COMPLETE 2026-08-24]

Goal: a second contributor works here for a week and misses nothing they would act on. All five shipped: deploy keys, commit statuses with require-checks gating, email notifications, inline review threads, and required approvals with CODEOWNERS and require-resolved.

  • #22 deploy keys — smallest item, unblocks CI checkout; the scope already exists in the policy layer
  • #1 commit statuses API and MR check display
  • #3 email notifications for issue/MR activity
  • #2 inline review comments on MR diffs
  • #19 required approvals and CODEOWNERS (builds on #1 and #2)

Phase 2 — a product, not a debug view [COMPLETE 2026-08-24; #30 activity graph follows on]

Goal: the site looks and reads like something you would recommend. Mostly web-layer; descriptions and profiles already landed as the first step.

  • #10 design revamp — closed 2026-08-24 after review (further design work is iteration under new issues) — shipped 2026-08-24, open pending visual review
  • #6 cross-references (#N) and @mentions — done 2026-08-24 (rendering-side; backlinks and mention notifications later)
  • #23 archived repos and topics — done 2026-08-24 (topic filtering rides along with search, #7)
  • #24 blame view — done 2026-08-24
  • #7 search — done 2026-08-24 (repo search by name/desc/topic, per-repo git grep on web+SSH; cross-repo indexer only if ever needed)
  • #20 milestones and issue templates — done 2026-08-24
  • #30 activity graph on owner pages — done 2026-08-25 (commit_activity by verified author email, dedup by sha; 53-week grid on user/org pages; 2,643 commits backfilled on gitbay.org)
  • #31 issue actions from commit messages — done 2026-08-24 (closes/fixes/resolves #N closes on landing; bare #N leaves a comment)

Phase 3 — other people's forges [COMPLETE 2026-08-24]

Goal: someone who is not the author runs an instance and moves their work to it.

  • #26 release engineering — done 2026-08-24 except artifact hosting, which waits on #8 (go-install vanity live, release.sh, CHANGELOG, Homebrew formula in krz/homebrew-tap) imports, Homebrew/deb — the adoption gate for everything below
  • #27 repository maintenance — done 2026-08-24 (admin gc/stats, weekly gitbay-gc.timer)
  • #8 releases — done 2026-08-24 (notes + assets; v0.1.0 binaries hosted)
  • #17 issue/PR history import from GitHub — done 2026-08-24
  • #18 push/pull mirroring — done 2026-08-24 (worker sync, read-only pull mirrors)
  • #29 account migration — done 2026-08-24 (bundle export/replay + client-side git mirror; no lock-in, ever; the export bundle doubles as a user-level backup)
  • #14 audit logging and multi-user hardening — done 2026-08-24 (quotas and key-expiry warnings ride with #28)
  • #9 web signup for open/invite instances — done 2026-08-24

Phase 4 — reach

Bigger bets, each valuable independently; order by appetite.

  • #13 CI/CD — done 2026-08-25 (.gitbay/ci.yml jobs, gitbay-runner over SSH on bay1, statuses feed require-checks; the forge never executes repository content itself)
  • #16 Git LFS
  • #15 static pages — done 2026-08-25 (public repos' pages branches on <owner>.<pages domain>, separate origin; gitbay.org deployment awaits the domain)
  • #11 iOS app (hutch-based) and #12 Android
  • #21 teams within orgs — done 2026-08-25 (members-role scoping + per-repo team grants)
  • #25 wikis — done 2026-08-25 (push-edited .wiki companions; krz/gitbay has one)

Done for the wiki half (2026-08-25): the docs now live in this wiki, dogfooding #25. When #15 (pages) lands they can graduate to a published site.

Phase 5 — the web grows up [COMPLETE 2026-08-26; v0.5.0 and v1.0.0, #35]

Two goals, one structure. The design needs sustained iteration, and the web needs enough capability that nobody calls it useless — without diluting CLI-first.

Identity, settled

The CLI is the complete interface: every capability exists over SSH, and web writes call the same control handlers. The web is the reading, reviewing, and responding surface — its bar is that a maintainer can complete the triage/review/merge loop from a browser. Deliberately CLI-only forever: secrets, mirror tokens, domain claims, and anything else whose input is a credential (stdin discipline). No-JS pages remain the baseline.

Current web write surface (audit 2026-08-25)

repo create, file edit, issue create/comment/edit, MR comment/edit, pin. Everything else is read-only.

Foundations (before page work)

  • Navigation IA: ten flat repo tabs wrap on mobile. Regroup — code (files/log/refs), work (issues/MRs/builds), publish (releases/wiki) — search and archive demoted to compact affordances.
  • Type scale and spacing rhythm pass; consistent card/list grammar.
  • Accessibility baseline: landmarks, focus states, contrast audit, skip link; keyboard-only walk of every page.
  • Diff renderer: syntax-highlighted diffs, per-file sections with stats and collapse — shared by commit and MR pages.
  • Empty states everywhere a list can be empty.

Page workstreams (design + parity land together)

Each ends with a screenshot checkpoint (both schemes, three widths) before merge.

  1. MR page: timeline/diff layout, review actions (approve/request changes), thread resolve, merge button with gate status, retarget; MR create from the web (branch picker).
  2. Issues: close/reopen, labels, assignees, milestone from the web; list filtering that matches the CLI's.
  3. Repo home: header with latest-commit line and clone box that doesn't fight the tree; file table polish.
  4. Dashboard: review requests, assigned work, recent activity feed — a reason to set it as a browser home page.
  5. Commit + log: statuses inline, signature chips tightened, log filtering UI for the ?path= history.
  6. Owner/org: team visibility, member management for org admins.
  7. Settings surface (repo admins): description, website, topics, branch protection and merge gates, visibility, archive — the safe subset of repo settings; plus SSH key management for accounts (add/remove keys from an authenticated session).
  8. Releases/builds: create and edit releases, retrigger builds.

Outcome

All eight page workstreams landed, plus the foundations. The web is now the reading, reviewing and responding surface it was scoped to be: a maintainer completes the triage/review/merge loop, manages their own keys and addresses, and runs an organization from a browser. The diff renderer (foldable per-file sections, line-number gutters, syntax highlighting per hunk per side) is shared by the commit and merge request pages. Repository homes state their own facts — commits, branches, tags, license, latest release, build status, language census, contributors resolved to accounts by verified email.

Still SSH-only by design, and listed as such on Parity: token minting, account export, secrets, mirror tokens, domain claims, repository delete and transfer, organization create/rename/delete.

Guardrails

  • PARITY page in this wiki: a maintained matrix of capability x surface (SSH/CLI/web/API), updated in the MR that changes it.
  • Rule for new features: lands over SSH first; if it belongs to the triage/review/respond loop it lands on the web in the same MR.
  • The view-only mode guarantee stays structural: accounts-mode routes never registered there.

Phase S — security (cross-cutting)

Not a sequential phase: items land alongside whatever phase is active, and the whole set gates flipping gitbay.org to open registration.

  • #14 audit logging, rate limiting, quotas, user disable — the multi-user half

  • #28 hardening umbrella — concrete items done 2026-08-24 (umbrella stays open for ongoing work). Both layers landed:

    • software: fuzz targets for every attacker-facing parser (found and fixed a decodeArmor slice bug), CSP + security headers, govulncheck in deploy/audit.sh (fixed circl GO-2026-4550), token comparison audit (hash-lookup, no Go-level compare), Threat-Model, optional minisign over release manifests
    • host: systemd sandbox (SystemCallFilter=@system-service, PrivateDevices, LockPersonality, MemoryDenyWriteExecute, …), unattended-upgrades, fail2ban + MaxStartups=/=MaxAuthTries on the admin sshd, hourly disk/service/cert monitoring; DB file modes 0750, litestream noted for continuous replication. Applied to bay1.

Already true and worth preserving (the threat model will write these down): the forge never executes repository content; no server signing key; repo-authored HTML never renders on the forge origin; tokens and sessions stored as hashes only; SSRF guards at registration and dial time; private repositories indistinguishable from nonexistent.

Explicitly not planned

Recorded so their absence reads as a decision, not an oversight:

  • container/package registry — scope creep away from "forge"; external registries integrate via CI
  • email patch flow — revisit only if sourcehut-style demand appears
  • federation (ForgeFed) and Postgres — no current need at this scale

Decisions

  • gitbay.org will eventually be open to all. (Decided 2026-08-24.) Sequencing consequence: before flipping registration = "open", the instance needs #14 (audit log, rate limiting, quotas), #9 (web signup), an SMTP relay configured for verification mail, and enough of Phase 1 that new users get a credible product. Interim step: invite mode for early collaborators as soon as [mail] is configured.
  • Versioning: semver, starting at v0.1.0 on the current state. 0.x signals moving surfaces; protocol_version increments only on breaking envelope/command changes and is otherwise decoupled from release numbers. v1.0.0 when Phase 1 and #26 land. Tags are annotated and signed.
  • Second contributors: invite mode is the on-ramp (their keys and verified emails make signed-main enforceable for them too). A CONTRIBUTING file states the workflow: fork on gitbay.org, MR with signed commits, go test ./... green, review required once #19 exists. No CLA — 0BSD needs none; sign-off optional.