docs/roadmap.org

  1#+title: gitbay roadmap
  2
  3Status and direction as of 2026-08-24. Issue numbers reference this
  4repository's tracker; this file is the narrative, the tracker is the
  5truth.
  6
  7* Where things stand
  8
  9Everything in the original plan is built, tested end-to-end against real
 10git/ssh/sshd/gpg, and running in production at gitbay.org: the SSH
 11control plane (usable from bare OpenSSH, enforced by test), git over
 12SSH/HTTPS/git://, signature verification with six states and epoch
 13caching, protected branches and =require_signed_commits= (push-time and
 14merge-time), issues, merge requests with four merge strategies, orgs
 15with membership-derived access, rename/transfer, repo import, invite and
 16open registration with SMTP verification, ACME TLS, the read-only and
 17accounts web modes, the JSON API fronting the whole command registry,
 18signed webhooks with retries and dead-lettering, restore-tested backups,
 19the =gitbay= CLI, and docs. The instance hosts 65 repositories including
 20this one, and its own development already runs through its issues and
 21merge requests.
 22
 23What it is today: an excellent forge for its author and for CLI-native
 24individuals. What it is not yet: a forge a GitHub-habituated *team*
 25would stay on, or a project outsiders can easily run themselves.
 26
 27* Phase 1 — collaboration credibility [COMPLETE 2026-08-24]
 28
 29Goal: a second contributor works here for a week and misses nothing they
 30would act on. All five shipped: deploy keys, commit statuses with
 31require-checks gating, email notifications, inline review threads, and
 32required approvals with CODEOWNERS and require-resolved.
 33
 34- [[https://gitbay.org/krz/gitbay/issues/22][#22]] deploy keys — smallest item, unblocks CI checkout; the scope
 35  already exists in the policy layer
 36- [[https://gitbay.org/krz/gitbay/issues/1][#1]] commit statuses API and MR check display
 37- [[https://gitbay.org/krz/gitbay/issues/3][#3]] email notifications for issue/MR activity
 38- [[https://gitbay.org/krz/gitbay/issues/2][#2]] inline review comments on MR diffs
 39- [[https://gitbay.org/krz/gitbay/issues/19][#19]] required approvals and CODEOWNERS (builds on #1 and #2)
 40
 41* Phase 2 — a product, not a debug view
 42
 43Goal: the site looks and reads like something you would recommend.
 44Mostly web-layer; descriptions and profiles already landed as the first
 45step.
 46
 47- [[https://gitbay.org/krz/gitbay/issues/10][#10]] design revamp (umbrella: tokens, typography, identity, mobile)
 48  — shipped 2026-08-24, open pending visual review
 49- [[https://gitbay.org/krz/gitbay/issues/6][#6]] cross-references (#N) and @mentions — done 2026-08-24
 50  (rendering-side; backlinks and mention notifications later)
 51- [[https://gitbay.org/krz/gitbay/issues/23][#23]] archived repos and topics — done 2026-08-24 (topic
 52  filtering rides along with search, #7)
 53- [[https://gitbay.org/krz/gitbay/issues/24][#24]] blame view — done 2026-08-24
 54- [[https://gitbay.org/krz/gitbay/issues/7][#7]] search — done 2026-08-24 (repo search by name/desc/topic,
 55  per-repo git grep on web+SSH; cross-repo indexer only if ever needed)
 56- [[https://gitbay.org/krz/gitbay/issues/20][#20]] milestones and issue templates — done 2026-08-24
 57- [[https://gitbay.org/krz/gitbay/issues/30][#30]] activity graph on owner pages (platform-recorded activity
 58  signal; events table already covers issues/MRs, extend to commits)
 59- [[https://gitbay.org/krz/gitbay/issues/31][#31]] issue actions from commit messages — done 2026-08-24
 60  (closes/fixes/resolves #N closes on landing; bare #N leaves a comment)
 61
 62* Phase 3 — other people's forges
 63
 64Goal: someone who is not the author runs an instance and moves their
 65work to it.
 66
 67- [[https://gitbay.org/krz/gitbay/issues/26][#26]] release engineering: versioned builds, go-install vanity
 68  imports, Homebrew/deb — the adoption gate for everything below
 69- [[https://gitbay.org/krz/gitbay/issues/27][#27]] repository maintenance (admin gc/stats, scheduled repack)
 70- [[https://gitbay.org/krz/gitbay/issues/8][#8]] releases (notes + assets; also hosts gitbay's own binaries)
 71- [[https://gitbay.org/krz/gitbay/issues/17][#17]] issue/PR history import from GitHub
 72- [[https://gitbay.org/krz/gitbay/issues/18][#18]] push/pull mirroring for gradual migration
 73- [[https://gitbay.org/krz/gitbay/issues/29][#29]] account migration between gitbay instances — no lock-in,
 74  ever; the export bundle doubles as a user-level backup
 75- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging and multi-user hardening
 76- [[https://gitbay.org/krz/gitbay/issues/9][#9]] web signup for open/invite instances
 77
 78* Phase 4 — reach
 79
 80Bigger bets, each valuable independently; order by appetite.
 81
 82- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD via external runners (after #1; the forge never executes
 83  repository content)
 84- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS
 85- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static page hosting (needs the separate-origin decision)
 86- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android
 87- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs
 88- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis
 89
 90When #15 (pages) and #25 (wikis) land, =docs/= moves out of the blob
 91view and becomes gitbay.org's own published documentation site — the
 92docs dogfooding the features the same way the tracker and MRs already
 93do.
 94
 95* Phase S — security (cross-cutting)
 96
 97Not a sequential phase: items land alongside whatever phase is active,
 98and the whole set gates flipping gitbay.org to open registration.
 99
100- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
101  multi-user half
102- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — the rest, both layers:
103  - software: fuzz all attacker-facing parsers (pkt-line, SSHSIG,
104    commit, armor), web security headers (CSP et al.), govulncheck,
105    constant-time comparison audit, a written threat model, signed
106    releases
107  - host: unattended OS patching, tighter systemd sandboxing
108    (SystemCallFilter and friends), auth throttling on both SSH
109    surfaces, database file modes and continuous replication,
110    service/disk/cert monitoring
111
112Already true and worth preserving (the threat model will write these
113down): the forge never executes repository content; no server signing
114key; repo-authored HTML never renders on the forge origin; tokens and
115sessions stored as hashes only; SSRF guards at registration and dial
116time; private repositories indistinguishable from nonexistent.
117
118* Explicitly not planned
119
120Recorded so their absence reads as a decision, not an oversight:
121
122- container/package registry — scope creep away from "forge"; external
123  registries integrate via CI
124- email patch flow — revisit only if sourcehut-style demand appears
125- federation (ForgeFed) and Postgres — no current need at this scale
126
127* Decisions
128
129- **gitbay.org will eventually be open to all.** (Decided 2026-08-24.)
130  Sequencing consequence: before flipping =registration = "open"=, the
131  instance needs #14 (audit log, rate limiting, quotas), #9 (web
132  signup), an SMTP relay configured for verification mail, and enough
133  of Phase 1 that new users get a credible product. Interim step:
134  invite mode for early collaborators as soon as [mail] is configured.
135- **Versioning**: semver, starting at v0.1.0 on the current state.
136  0.x signals moving surfaces; =protocol_version= increments only on
137  breaking envelope/command changes and is otherwise decoupled from
138  release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
139  annotated and signed.
140- **Second contributors**: invite mode is the on-ramp (their keys and
141  verified emails make signed-main enforceable for them too). A
142  CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
143  signed commits, =go test ./...= green, review required once #19
144  exists. No CLA — 0BSD needs none; sign-off optional.