| @@ -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. |