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 [COMPLETE 2026-08-24]
 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 — done 2026-08-24 except artifact
 68  hosting, which waits on #8 (go-install vanity live, release.sh,
 69  CHANGELOG, Homebrew formula in krz/homebrew-tap)
 70  imports, Homebrew/deb — the adoption gate for everything below
 71- [[https://gitbay.org/krz/gitbay/issues/27][#27]] repository maintenance — done 2026-08-24 (admin gc/stats, weekly gitbay-gc.timer)
 72- [[https://gitbay.org/krz/gitbay/issues/8][#8]] releases — done 2026-08-24 (notes + assets; v0.1.0 binaries hosted)
 73- [[https://gitbay.org/krz/gitbay/issues/17][#17]] issue/PR history import from GitHub — done 2026-08-24
 74- [[https://gitbay.org/krz/gitbay/issues/18][#18]] push/pull mirroring — done 2026-08-24 (worker sync, read-only pull mirrors)
 75- [[https://gitbay.org/krz/gitbay/issues/29][#29]] account migration — done 2026-08-24 (bundle export/replay + client-side git mirror; no lock-in,
 76  ever; the export bundle doubles as a user-level backup)
 77- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging and multi-user hardening — done 2026-08-24 (quotas and key-expiry warnings ride with #28)
 78- [[https://gitbay.org/krz/gitbay/issues/9][#9]] web signup for open/invite instances — done 2026-08-24
 79
 80* Phase 4 — reach
 81
 82Bigger bets, each valuable independently; order by appetite.
 83
 84- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD via external runners (after #1; the forge never executes
 85  repository content)
 86- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS
 87- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static page hosting (needs the separate-origin decision)
 88- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android
 89- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs
 90- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis
 91
 92When #15 (pages) and #25 (wikis) land, =docs/= moves out of the blob
 93view and becomes gitbay.org's own published documentation site — the
 94docs dogfooding the features the same way the tracker and MRs already
 95do.
 96
 97* Phase S — security (cross-cutting)
 98
 99Not a sequential phase: items land alongside whatever phase is active,
100and the whole set gates flipping gitbay.org to open registration.
101
102- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
103  multi-user half
104- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — the rest, both layers:
105  - software: fuzz all attacker-facing parsers (pkt-line, SSHSIG,
106    commit, armor), web security headers (CSP et al.), govulncheck,
107    constant-time comparison audit, a written threat model, signed
108    releases
109  - host: unattended OS patching, tighter systemd sandboxing
110    (SystemCallFilter and friends), auth throttling on both SSH
111    surfaces, database file modes and continuous replication,
112    service/disk/cert monitoring
113
114Already true and worth preserving (the threat model will write these
115down): the forge never executes repository content; no server signing
116key; repo-authored HTML never renders on the forge origin; tokens and
117sessions stored as hashes only; SSRF guards at registration and dial
118time; private repositories indistinguishable from nonexistent.
119
120* Explicitly not planned
121
122Recorded so their absence reads as a decision, not an oversight:
123
124- container/package registry — scope creep away from "forge"; external
125  registries integrate via CI
126- email patch flow — revisit only if sourcehut-style demand appears
127- federation (ForgeFed) and Postgres — no current need at this scale
128
129* Decisions
130
131- **gitbay.org will eventually be open to all.** (Decided 2026-08-24.)
132  Sequencing consequence: before flipping =registration = "open"=, the
133  instance needs #14 (audit log, rate limiting, quotas), #9 (web
134  signup), an SMTP relay configured for verification mail, and enough
135  of Phase 1 that new users get a credible product. Interim step:
136  invite mode for early collaborators as soon as [mail] is configured.
137- **Versioning**: semver, starting at v0.1.0 on the current state.
138  0.x signals moving surfaces; =protocol_version= increments only on
139  breaking envelope/command changes and is otherwise decoupled from
140  release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
141  annotated and signed.
142- **Second contributors**: invite mode is the on-ramp (their keys and
143  verified emails make signed-main enforceable for them too). A
144  CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
145  signed commits, =go test ./...= green, review required once #19
146  exists. No CLA — 0BSD needs none; sign-off optional.