Commit `f7bbcda4ad`

f7bbcda4ad629e6048c752aa8d67ca89aa4a4277

parent: 6f16ad5df0

Verified · cmc ci/build: success ci/test: success

cmc <hello@cleberg.net> · 2026-09-07 17:58 UTC

wiki, README: drop the Roadmap page

Every phase it narrates is complete and the tracker, CHANGELOG.org and
the milestones carry the status. Its "explicitly not planned" list
moves to the FAQ; its decisions are all executed or recorded elsewhere
(CHANGELOG.org for versioning, CONTRIBUTING.org for contributors, the
Threat-Model for the security invariants).

Layout: unified · split

.gitbay/wiki/FAQ.org +5

	@@ -12,3 +12,8 @@
12	- Moving from GitHub? :: =gitbay repo import= (git data) then	12	- Moving from GitHub? :: =gitbay repo import= (git data) then
13	=gitbay repo import-issues= (history); =repo mirror= covers the	13	=gitbay repo import-issues= (history); =repo mirror= covers the
14	transition window.	14	transition window.
		15	- What is not planned? :: A container or package registry (scope creep
		16	away from "forge"; external registries integrate through CI), an
		17	email patch flow (revisit only if sourcehut-style demand appears),
		18	federation and Postgres (no need at this scale). Recorded so the
		19	absence reads as a decision, not an oversight.

.gitbay/wiki/Home.org −1

	@@ -8,7 +8,6 @@ CLI-first git forge: SSH is the API, the web is a rendering.
8	- [[Stacked-MRs][Stacked merge requests]] — dependent merge requests, merged one layer at a time	8	- [[Stacked-MRs][Stacked merge requests]] — dependent merge requests, merged one layer at a time
9	- [[Admin][Admin guide]] — install, configuration reference, backup, security	9	- [[Admin][Admin guide]] — install, configuration reference, backup, security
10	- [[API][API and webhooks]] — the JSON API contract, tokens, payloads	10	- [[API][API and webhooks]] — the JSON API contract, tokens, payloads
11	- [[Roadmap][Roadmap]] — status, phases, decisions, what is not planned
12	- [[Threat-Model][Threat model]] — what the forge trusts and never does	11	- [[Threat-Model][Threat model]] — what the forge trusts and never does
13	- [[Parity][Parity]] — what each surface can do, and what stays SSH-only	12	- [[Parity][Parity]] — what each surface can do, and what stays SSH-only
14	- [[Performance][Performance]] — stress-test numbers from importing git.git	13	- [[Performance][Performance]] — stress-test numbers from importing git.git

.gitbay/wiki/Roadmap.org deleted −247

	@@ -1,247 +0,0 @@
1	#+title: gitbay roadmap
2
3	Status and direction as of 2026-08-24. Issue numbers reference this
4	repository's tracker; this file is the narrative, the tracker is the
5	truth.
6
7	* Where things stand
8
9	Everything in the original plan is built, tested end-to-end against real
10	git/ssh/sshd/gpg, and running in production at gitbay.org: the SSH
11	control plane (usable from bare OpenSSH, enforced by test), git over
12	SSH/HTTPS/git://, signature verification with six states and epoch
13	caching, protected branches and =require_signed_commits= (push-time and
14	merge-time), issues, merge requests with four merge strategies, orgs
15	with membership-derived access, rename/transfer, repo import, invite and
16	open registration with SMTP verification, ACME TLS, the read-only and
17	accounts web modes, the JSON API fronting the whole command registry,
18	signed webhooks with retries and dead-lettering, restore-tested backups,
19	the =gitbay= CLI, and docs. The instance hosts 65 repositories including
20	this one, and its own development already runs through its issues and
21	merge requests.
22
23	What it is today: an excellent forge for its author and for CLI-native
24	individuals. What it is not yet: a forge a GitHub-habituated team
25	would stay on, or a project outsiders can easily run themselves.
26
27	* Phase 1 — collaboration credibility [COMPLETE 2026-08-24]
28
29	Goal: a second contributor works here for a week and misses nothing they
30	would act on. All five shipped: deploy keys, commit statuses with
31	require-checks gating, email notifications, inline review threads, and
32	required 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
43	Goal: the site looks and reads like something you would recommend.
44	Mostly web-layer; descriptions and profiles already landed as the first
45	step.
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
65	Goal: someone who is not the author runs an instance and moves their
66	work 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
83	Bigger 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, moved into the repository 2026-09-05 ([[https://gitbay.org/krz/gitbay/issues/170][#170]])
95
96	Done for the wiki half (2026-08-25): the docs now live in this wiki,
97	dogfooding #25. When #15 (pages) lands they can graduate to a published
98	site.
99
100	A wiki was a companion bare repo at =<name>.wiki.git= with no row in the
101	store, invisible to backups, quotas, search and the activity feed, and
102	writable only by push. Since [[https://gitbay.org/krz/gitbay/issues/170][#170]] pages live at =.gitbay/wiki/= on the
103	default branch, beside =ci.yml= and =CODEOWNERS=: one repository, one
104	clone, one backup, one permission model. This page's own history came
105	across intact. The companion path is gone rather than deprecated —
106	cloning =krz/gitbay.wiki= now fails with =repository not found=.
107
108	The trade is that prose edits are commits on the default branch, so they
109	go through a branch and a merge request like any other file, and they
110	would queue every CI job. [[https://gitbay.org/krz/gitbay/issues/169][#169]] added =paths= and =paths-ignore= to
111	=.gitbay/ci.yml= for that, and [[https://gitbay.org/krz/gitbay/issues/171][#171]] made the filter apply to a branch's
112	first push, which is the shape every change here has.
113
114	* 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]]]
115
116	Two goals, one structure. The design needs sustained iteration, and the
117	web needs enough capability that nobody calls it useless — without
118	diluting CLI-first.
119
120	** Identity, settled
121
122	The CLI is the complete interface: every capability exists over SSH,
123	and web writes call the same control handlers. The web is the reading,
124	reviewing, and responding surface — its bar is that a maintainer can
125	complete the triage/review/merge loop from a browser. Deliberately
126	CLI-only forever: secrets, mirror tokens, domain claims, and anything
127	else whose input is a credential (stdin discipline). No-JS pages remain
128	the baseline.
129
130	** Current web write surface (audit 2026-08-25)
131
132	repo create, file edit, issue create/comment/edit, MR comment/edit,
133	pin. Everything else is read-only.
134
135	** Foundations (before page work)
136
137	- Navigation IA: ten flat repo tabs wrap on mobile. Regroup — code
138	(files/log/refs), work (issues/MRs/builds), publish
139	(releases/wiki) — search and archive demoted to compact affordances.
140	- Type scale and spacing rhythm pass; consistent card/list grammar.
141	- Accessibility baseline: landmarks, focus states, contrast audit,
142	skip link; keyboard-only walk of every page.
143	- Diff renderer: syntax-highlighted diffs, per-file sections with
144	stats and collapse — shared by commit and MR pages.
145	- Empty states everywhere a list can be empty.
146
147	** Page workstreams (design + parity land together)
148
149	Each ends with a screenshot checkpoint (both schemes, three widths)
150	before merge.
151
152	1. MR page: timeline/diff layout, review actions (approve/request
153	changes), thread resolve, merge button with gate status, retarget;
154	MR create from the web (branch picker).
155	2. Issues: close/reopen, labels, assignees, milestone from the web;
156	list filtering that matches the CLI's.
157	3. Repo home: header with latest-commit line and clone box that
158	doesn't fight the tree; file table polish.
159	4. Dashboard: review requests, assigned work, recent activity feed —
160	a reason to set it as a browser home page.
161	5. Commit + log: statuses inline, signature chips tightened, log
162	filtering UI for the ?path= history.
163	6. Owner/org: team visibility, member management for org admins.
164	7. Settings surface (repo admins): description, website, topics,
165	branch protection and merge gates, visibility, archive — the
166	safe subset of repo settings; plus SSH key management for accounts
167	(add/remove keys from an authenticated session).
168	8. Releases/builds: create and edit releases, retrigger builds.
169
170	** Outcome
171
172	All eight page workstreams landed, plus the foundations. The web is now
173	the reading, reviewing and responding surface it was scoped to be: a
174	maintainer completes the triage/review/merge loop, manages their own
175	keys and addresses, and runs an organization from a browser. The diff
176	renderer (foldable per-file sections, line-number gutters, syntax
177	highlighting per hunk per side) is shared by the commit and merge
178	request pages. Repository homes state their own facts — commits,
179	branches, tags, license, latest release, build status, language census,
180	contributors resolved to accounts by verified email.
181
182	Still SSH-only by design, and listed as such on [[Parity]]: token
183	minting, account export, secrets, mirror tokens, domain claims,
184	repository delete and transfer, organization create/rename/delete.
185
186	** Guardrails
187
188	- PARITY page in this wiki: a maintained matrix of capability x
189	surface (SSH/CLI/web/API), updated in the MR that changes it.
190	- Rule for new features: lands over SSH first; if it belongs to the
191	triage/review/respond loop it lands on the web in the same MR.
192	- The view-only mode guarantee stays structural: accounts-mode routes
193	never registered there.
194
195	* Phase S — security (cross-cutting)
196
197	Not a sequential phase: items land alongside whatever phase is active,
198	and the whole set gates flipping gitbay.org to open registration.
199
200	- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
201	multi-user half
202	- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — concrete items done 2026-08-24
203	(umbrella stays open for ongoing work). Both layers landed:
204	- software: fuzz targets for every attacker-facing parser (found and
205	fixed a decodeArmor slice bug), CSP + security headers, govulncheck
206	in =deploy/audit.sh= (fixed circl GO-2026-4550), token comparison
207	audit (hash-lookup, no Go-level compare), [[Threat-Model]],
208	optional minisign over release manifests
209	- host: systemd sandbox (=SystemCallFilter=@system-service=,
210	=PrivateDevices=, =LockPersonality=, =MemoryDenyWriteExecute=, …),
211	unattended-upgrades, fail2ban + =MaxStartups=/=MaxAuthTries= on the
212	admin sshd, hourly disk/service/cert monitoring; DB file modes 0750,
213	litestream noted for continuous replication. Applied to bay1.
214
215	Already true and worth preserving (the threat model will write these
216	down): the forge never executes repository content; no server signing
217	key; repo-authored HTML never renders on the forge origin; tokens and
218	sessions stored as hashes only; SSRF guards at registration and dial
219	time; private repositories indistinguishable from nonexistent.
220
221	* Explicitly not planned
222
223	Recorded so their absence reads as a decision, not an oversight:
224
225	- container/package registry — scope creep away from "forge"; external
226	registries integrate via CI
227	- email patch flow — revisit only if sourcehut-style demand appears
228	- federation (ForgeFed) and Postgres — no current need at this scale
229
230	* Decisions
231
232	- gitbay.org will eventually be open to all. (Decided 2026-08-24.)
233	Sequencing consequence: before flipping =registration = "open"=, the
234	instance needs #14 (audit log, rate limiting, quotas), #9 (web
235	signup), an SMTP relay configured for verification mail, and enough
236	of Phase 1 that new users get a credible product. Interim step:
237	invite mode for early collaborators as soon as [mail] is configured.
238	- Versioning: semver, starting at v0.1.0 on the current state.
239	0.x signals moving surfaces; =protocol_version= increments only on
240	breaking envelope/command changes and is otherwise decoupled from
241	release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
242	annotated and signed.
243	- Second contributors: invite mode is the on-ramp (their keys and
244	verified emails make signed-main enforceable for them too). A
245	CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
246	signed commits, =go test ./...= green, review required once #19
247	exists. No CLA — 0BSD needs none; sign-off optional.

README.org −1

	@@ -110,7 +110,6 @@ wiki feature:
110	- [[https://gitbay.org/krz/gitbay/wiki/Users][user guide]] — accounts, keys, verified commits, repos, issues, MRs, scripting	110	- [[https://gitbay.org/krz/gitbay/wiki/Users][user guide]] — accounts, keys, verified commits, repos, issues, MRs, scripting
111	- [[https://gitbay.org/krz/gitbay/wiki/Admin][admin guide]] — install, full configuration reference, backup/restore, security	111	- [[https://gitbay.org/krz/gitbay/wiki/Admin][admin guide]] — install, full configuration reference, backup/restore, security
112	- [[https://gitbay.org/krz/gitbay/wiki/API][API and webhooks]] — the JSON API contract, tokens, webhook payloads and HMAC	112	- [[https://gitbay.org/krz/gitbay/wiki/API][API and webhooks]] — the JSON API contract, tokens, webhook payloads and HMAC
113	- [[https://gitbay.org/krz/gitbay/wiki/Roadmap][roadmap]] — status, phased plan, and what is deliberately not planned
114	- [[https://gitbay.org/krz/gitbay/wiki/Threat-Model][threat model]] — what the forge trusts and never does	113	- [[https://gitbay.org/krz/gitbay/wiki/Threat-Model][threat model]] — what the forge trusts and never does
115		114
116	* Contributing	115	* Contributing

Commit f7bbcda4ad

Commit `f7bbcda4ad`