.gitbay/wiki/Roadmap.org
233 lines · 12827 bytes
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 [COMPLETE 2026-08-24; #30 activity graph follows on]
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 — closed 2026-08-24 after review (further design work is iteration under new issues)
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 — done 2026-08-25 (commit_activity
58 by verified author email, dedup by sha; 53-week grid on user/org pages;
59 2,643 commits backfilled on gitbay.org)
60- [[https://gitbay.org/krz/gitbay/issues/31][#31]] issue actions from commit messages — done 2026-08-24
61 (closes/fixes/resolves #N closes on landing; bare #N leaves a comment)
62
63* Phase 3 — other people's forges [COMPLETE 2026-08-24]
64
65Goal: someone who is not the author runs an instance and moves their
66work to it.
67
68- [[https://gitbay.org/krz/gitbay/issues/26][#26]] release engineering — done 2026-08-24 except artifact
69 hosting, which waits on #8 (go-install vanity live, release.sh,
70 CHANGELOG, Homebrew formula in krz/homebrew-tap)
71 imports, Homebrew/deb — the adoption gate for everything below
72- [[https://gitbay.org/krz/gitbay/issues/27][#27]] repository maintenance — done 2026-08-24 (admin gc/stats, weekly gitbay-gc.timer)
73- [[https://gitbay.org/krz/gitbay/issues/8][#8]] releases — done 2026-08-24 (notes + assets; v0.1.0 binaries hosted)
74- [[https://gitbay.org/krz/gitbay/issues/17][#17]] issue/PR history import from GitHub — done 2026-08-24
75- [[https://gitbay.org/krz/gitbay/issues/18][#18]] push/pull mirroring — done 2026-08-24 (worker sync, read-only pull mirrors)
76- [[https://gitbay.org/krz/gitbay/issues/29][#29]] account migration — done 2026-08-24 (bundle export/replay + client-side git mirror; no lock-in,
77 ever; the export bundle doubles as a user-level backup)
78- [[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)
79- [[https://gitbay.org/krz/gitbay/issues/9][#9]] web signup for open/invite instances — done 2026-08-24
80
81* Phase 4 — reach
82
83Bigger bets, each valuable independently; order by appetite.
84
85- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD — done 2026-08-25 (.gitbay/ci.yml jobs, gitbay-runner over
86 SSH on bay1, statuses feed require-checks; the forge never executes
87 repository content itself)
88- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS
89- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static pages — done 2026-08-25 (public repos' =pages= branches on
90 <owner>.<pages domain>, separate origin; gitbay.org deployment awaits
91 the domain)
92- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android
93- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs — done 2026-08-25 (members-role scoping + per-repo team grants)
94- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis — done 2026-08-25 (push-edited .wiki companions; krz/gitbay has one)
95
96Done for the wiki half (2026-08-25): the docs now live in this wiki,
97dogfooding #25. When #15 (pages) lands they can graduate to a published
98site.
99
100* Phase 5 — the web grows up [COMPLETE 2026-08-26; v0.5.0 and v1.0.0, [[https://gitbay.org/krz/gitbay/issues/35][#35]]]
101
102Two goals, one structure. The design needs sustained iteration, and the
103web needs enough capability that nobody calls it useless — without
104diluting CLI-first.
105
106** Identity, settled
107
108The CLI is the complete interface: every capability exists over SSH,
109and web writes call the same control handlers. The web is the reading,
110reviewing, and responding surface — its bar is that a maintainer can
111complete the triage/review/merge loop from a browser. Deliberately
112CLI-only forever: secrets, mirror tokens, domain claims, and anything
113else whose input is a credential (stdin discipline). No-JS pages remain
114the baseline.
115
116** Current web write surface (audit 2026-08-25)
117
118repo create, file edit, issue create/comment/edit, MR comment/edit,
119pin. Everything else is read-only.
120
121** Foundations (before page work)
122
123- Navigation IA: ten flat repo tabs wrap on mobile. Regroup — code
124 (files/log/refs), work (issues/MRs/builds), publish
125 (releases/wiki) — search and archive demoted to compact affordances.
126- Type scale and spacing rhythm pass; consistent card/list grammar.
127- Accessibility baseline: landmarks, focus states, contrast audit,
128 skip link; keyboard-only walk of every page.
129- Diff renderer: syntax-highlighted diffs, per-file sections with
130 stats and collapse — shared by commit and MR pages.
131- Empty states everywhere a list can be empty.
132
133** Page workstreams (design + parity land together)
134
135Each ends with a screenshot checkpoint (both schemes, three widths)
136before merge.
137
1381. MR page: timeline/diff layout, review actions (approve/request
139 changes), thread resolve, merge button with gate status, retarget;
140 MR create from the web (branch picker).
1412. Issues: close/reopen, labels, assignees, milestone from the web;
142 list filtering that matches the CLI's.
1433. Repo home: header with latest-commit line and clone box that
144 doesn't fight the tree; file table polish.
1454. Dashboard: review requests, assigned work, recent activity feed —
146 a reason to set it as a browser home page.
1475. Commit + log: statuses inline, signature chips tightened, log
148 filtering UI for the ?path= history.
1496. Owner/org: team visibility, member management for org admins.
1507. Settings surface (repo admins): description, website, topics,
151 branch protection and merge gates, visibility, archive — the
152 safe subset of repo settings; plus SSH key management for accounts
153 (add/remove keys from an authenticated session).
1548. Releases/builds: create and edit releases, retrigger builds.
155
156** Outcome
157
158All eight page workstreams landed, plus the foundations. The web is now
159the reading, reviewing and responding surface it was scoped to be: a
160maintainer completes the triage/review/merge loop, manages their own
161keys and addresses, and runs an organization from a browser. The diff
162renderer (foldable per-file sections, line-number gutters, syntax
163highlighting per hunk per side) is shared by the commit and merge
164request pages. Repository homes state their own facts — commits,
165branches, tags, license, latest release, build status, language census,
166contributors resolved to accounts by verified email.
167
168Still SSH-only by design, and listed as such on [[Parity]]: token
169minting, account export, secrets, mirror tokens, domain claims,
170repository delete and transfer, organization create/rename/delete.
171
172** Guardrails
173
174- PARITY page in this wiki: a maintained matrix of capability x
175 surface (SSH/CLI/web/API), updated in the MR that changes it.
176- Rule for new features: lands over SSH first; if it belongs to the
177 triage/review/respond loop it lands on the web in the same MR.
178- The view-only mode guarantee stays structural: accounts-mode routes
179 never registered there.
180
181* Phase S — security (cross-cutting)
182
183Not a sequential phase: items land alongside whatever phase is active,
184and the whole set gates flipping gitbay.org to open registration.
185
186- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
187 multi-user half
188- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — concrete items done 2026-08-24
189 (umbrella stays open for ongoing work). Both layers landed:
190 - software: fuzz targets for every attacker-facing parser (found and
191 fixed a decodeArmor slice bug), CSP + security headers, govulncheck
192 in =deploy/audit.sh= (fixed circl GO-2026-4550), token comparison
193 audit (hash-lookup, no Go-level compare), [[Threat-Model]],
194 optional minisign over release manifests
195 - host: systemd sandbox (=SystemCallFilter=@system-service=,
196 =PrivateDevices=, =LockPersonality=, =MemoryDenyWriteExecute=, …),
197 unattended-upgrades, fail2ban + =MaxStartups=/=MaxAuthTries= on the
198 admin sshd, hourly disk/service/cert monitoring; DB file modes 0750,
199 litestream noted for continuous replication. Applied to bay1.
200
201Already true and worth preserving (the threat model will write these
202down): the forge never executes repository content; no server signing
203key; repo-authored HTML never renders on the forge origin; tokens and
204sessions stored as hashes only; SSRF guards at registration and dial
205time; private repositories indistinguishable from nonexistent.
206
207* Explicitly not planned
208
209Recorded so their absence reads as a decision, not an oversight:
210
211- container/package registry — scope creep away from "forge"; external
212 registries integrate via CI
213- email patch flow — revisit only if sourcehut-style demand appears
214- federation (ForgeFed) and Postgres — no current need at this scale
215
216* Decisions
217
218- **gitbay.org will eventually be open to all.** (Decided 2026-08-24.)
219 Sequencing consequence: before flipping =registration = "open"=, the
220 instance needs #14 (audit log, rate limiting, quotas), #9 (web
221 signup), an SMTP relay configured for verification mail, and enough
222 of Phase 1 that new users get a credible product. Interim step:
223 invite mode for early collaborators as soon as [mail] is configured.
224- **Versioning**: semver, starting at v0.1.0 on the current state.
225 0.x signals moving surfaces; =protocol_version= increments only on
226 breaking envelope/command changes and is otherwise decoupled from
227 release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
228 annotated and signed.
229- **Second contributors**: invite mode is the on-ramp (their keys and
230 verified emails make signed-main enforceable for them too). A
231 CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
232 signed commits, =go test ./...= green, review required once #19
233 exists. No CLA — 0BSD needs none; sign-off optional.