#+title: gitbay roadmap

Status and direction as of 2026-08-24. Issue numbers reference this
repository's tracker; this file is the narrative, the tracker is the
truth.

* Where things stand

Everything in the original plan is built, tested end-to-end against real
git/ssh/sshd/gpg, and running in production at gitbay.org: the SSH
control plane (usable from bare OpenSSH, enforced by test), git over
SSH/HTTPS/git://, signature verification with six states and epoch
caching, protected branches and =require_signed_commits= (push-time and
merge-time), issues, merge requests with four merge strategies, orgs
with membership-derived access, rename/transfer, repo import, invite and
open registration with SMTP verification, ACME TLS, the read-only and
accounts web modes, the JSON API fronting the whole command registry,
signed webhooks with retries and dead-lettering, restore-tested backups,
the =gitbay= CLI, and docs. The instance hosts 65 repositories including
this one, and its own development already runs through its issues and
merge requests.

What it is today: an excellent forge for its author and for CLI-native
individuals. What it is not yet: a forge a GitHub-habituated *team*
would stay on, or a project outsiders can easily run themselves.

* Phase 1 — collaboration credibility [COMPLETE 2026-08-24]

Goal: a second contributor works here for a week and misses nothing they
would act on. All five shipped: deploy keys, commit statuses with
require-checks gating, email notifications, inline review threads, and
required approvals with CODEOWNERS and require-resolved.

- [[https://gitbay.org/krz/gitbay/issues/22][#22]] deploy keys — smallest item, unblocks CI checkout; the scope
  already exists in the policy layer
- [[https://gitbay.org/krz/gitbay/issues/1][#1]] commit statuses API and MR check display
- [[https://gitbay.org/krz/gitbay/issues/3][#3]] email notifications for issue/MR activity
- [[https://gitbay.org/krz/gitbay/issues/2][#2]] inline review comments on MR diffs
- [[https://gitbay.org/krz/gitbay/issues/19][#19]] required approvals and CODEOWNERS (builds on #1 and #2)

* Phase 2 — a product, not a debug view [COMPLETE 2026-08-24; #30 activity graph follows on]

Goal: the site looks and reads like something you would recommend.
Mostly web-layer; descriptions and profiles already landed as the first
step.

- [[https://gitbay.org/krz/gitbay/issues/10][#10]] design revamp — closed 2026-08-24 after review (further design work is iteration under new issues)
  — shipped 2026-08-24, open pending visual review
- [[https://gitbay.org/krz/gitbay/issues/6][#6]] cross-references (#N) and @mentions — done 2026-08-24
  (rendering-side; backlinks and mention notifications later)
- [[https://gitbay.org/krz/gitbay/issues/23][#23]] archived repos and topics — done 2026-08-24 (topic
  filtering rides along with search, #7)
- [[https://gitbay.org/krz/gitbay/issues/24][#24]] blame view — done 2026-08-24
- [[https://gitbay.org/krz/gitbay/issues/7][#7]] search — done 2026-08-24 (repo search by name/desc/topic,
  per-repo git grep on web+SSH; cross-repo indexer only if ever needed)
- [[https://gitbay.org/krz/gitbay/issues/20][#20]] milestones and issue templates — done 2026-08-24
- [[https://gitbay.org/krz/gitbay/issues/30][#30]] activity graph on owner pages — done 2026-08-25 (commit_activity
  by verified author email, dedup by sha; 53-week grid on user/org pages;
  2,643 commits backfilled on gitbay.org)
- [[https://gitbay.org/krz/gitbay/issues/31][#31]] issue actions from commit messages — done 2026-08-24
  (closes/fixes/resolves #N closes on landing; bare #N leaves a comment)

* Phase 3 — other people's forges [COMPLETE 2026-08-24]

Goal: someone who is not the author runs an instance and moves their
work to it.

- [[https://gitbay.org/krz/gitbay/issues/26][#26]] release engineering — done 2026-08-24 except artifact
  hosting, which waits on #8 (go-install vanity live, release.sh,
  CHANGELOG, Homebrew formula in krz/homebrew-tap)
  imports, Homebrew/deb — the adoption gate for everything below
- [[https://gitbay.org/krz/gitbay/issues/27][#27]] repository maintenance — done 2026-08-24 (admin gc/stats, weekly gitbay-gc.timer)
- [[https://gitbay.org/krz/gitbay/issues/8][#8]] releases — done 2026-08-24 (notes + assets; v0.1.0 binaries hosted)
- [[https://gitbay.org/krz/gitbay/issues/17][#17]] issue/PR history import from GitHub — done 2026-08-24
- [[https://gitbay.org/krz/gitbay/issues/18][#18]] push/pull mirroring — done 2026-08-24 (worker sync, read-only pull mirrors)
- [[https://gitbay.org/krz/gitbay/issues/29][#29]] account migration — done 2026-08-24 (bundle export/replay + client-side git mirror; no lock-in,
  ever; the export bundle doubles as a user-level backup)
- [[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)
- [[https://gitbay.org/krz/gitbay/issues/9][#9]] web signup for open/invite instances — done 2026-08-24

* Phase 4 — reach

Bigger bets, each valuable independently; order by appetite.

- [[https://gitbay.org/krz/gitbay/issues/13][#13]] CI/CD — done 2026-08-25 (.gitbay/ci.yml jobs, gitbay-runner over
  SSH on bay1, statuses feed require-checks; the forge never executes
  repository content itself)
- [[https://gitbay.org/krz/gitbay/issues/16][#16]] Git LFS
- [[https://gitbay.org/krz/gitbay/issues/15][#15]] static pages — done 2026-08-25 (public repos' =pages= branches on
  <owner>.<pages domain>, separate origin; gitbay.org deployment awaits
  the domain)
- [[https://gitbay.org/krz/gitbay/issues/11][#11]] iOS app (hutch-based) and [[https://gitbay.org/krz/gitbay/issues/12][#12]] Android
- [[https://gitbay.org/krz/gitbay/issues/21][#21]] teams within orgs — done 2026-08-25 (members-role scoping + per-repo team grants)
- [[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]])

Done for the wiki half (2026-08-25): the docs now live in this wiki,
dogfooding #25. When #15 (pages) lands they can graduate to a published
site.

A wiki was a companion bare repo at =<name>.wiki.git= with no row in the
store, invisible to backups, quotas, search and the activity feed, and
writable only by push. Since [[https://gitbay.org/krz/gitbay/issues/170][#170]] pages live at =.gitbay/wiki/= on the
default branch, beside =ci.yml= and =CODEOWNERS=: one repository, one
clone, one backup, one permission model. This page's own history came
across intact. The companion path is gone rather than deprecated —
cloning =krz/gitbay.wiki= now fails with =repository not found=.

The trade is that prose edits are commits on the default branch, so they
go through a branch and a merge request like any other file, and they
would queue every CI job. [[https://gitbay.org/krz/gitbay/issues/169][#169]] added =paths= and =paths-ignore= to
=.gitbay/ci.yml= for that, and [[https://gitbay.org/krz/gitbay/issues/171][#171]] made the filter apply to a branch's
first push, which is the shape every change here has.

* 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]]]

Two goals, one structure. The design needs sustained iteration, and the
web needs enough capability that nobody calls it useless — without
diluting CLI-first.

** Identity, settled

The CLI is the complete interface: every capability exists over SSH,
and web writes call the same control handlers. The web is the reading,
reviewing, and responding surface — its bar is that a maintainer can
complete the triage/review/merge loop from a browser. Deliberately
CLI-only forever: secrets, mirror tokens, domain claims, and anything
else whose input is a credential (stdin discipline). No-JS pages remain
the baseline.

** Current web write surface (audit 2026-08-25)

repo create, file edit, issue create/comment/edit, MR comment/edit,
pin. Everything else is read-only.

** Foundations (before page work)

- Navigation IA: ten flat repo tabs wrap on mobile. Regroup — code
  (files/log/refs), work (issues/MRs/builds), publish
  (releases/wiki) — search and archive demoted to compact affordances.
- Type scale and spacing rhythm pass; consistent card/list grammar.
- Accessibility baseline: landmarks, focus states, contrast audit,
  skip link; keyboard-only walk of every page.
- Diff renderer: syntax-highlighted diffs, per-file sections with
  stats and collapse — shared by commit and MR pages.
- Empty states everywhere a list can be empty.

** Page workstreams (design + parity land together)

Each ends with a screenshot checkpoint (both schemes, three widths)
before merge.

1. MR page: timeline/diff layout, review actions (approve/request
   changes), thread resolve, merge button with gate status, retarget;
   MR create from the web (branch picker).
2. Issues: close/reopen, labels, assignees, milestone from the web;
   list filtering that matches the CLI's.
3. Repo home: header with latest-commit line and clone box that
   doesn't fight the tree; file table polish.
4. Dashboard: review requests, assigned work, recent activity feed —
   a reason to set it as a browser home page.
5. Commit + log: statuses inline, signature chips tightened, log
   filtering UI for the ?path= history.
6. Owner/org: team visibility, member management for org admins.
7. Settings surface (repo admins): description, website, topics,
   branch protection and merge gates, visibility, archive — the
   safe subset of repo settings; plus SSH key management for accounts
   (add/remove keys from an authenticated session).
8. Releases/builds: create and edit releases, retrigger builds.

** Outcome

All eight page workstreams landed, plus the foundations. The web is now
the reading, reviewing and responding surface it was scoped to be: a
maintainer completes the triage/review/merge loop, manages their own
keys and addresses, and runs an organization from a browser. The diff
renderer (foldable per-file sections, line-number gutters, syntax
highlighting per hunk per side) is shared by the commit and merge
request pages. Repository homes state their own facts — commits,
branches, tags, license, latest release, build status, language census,
contributors resolved to accounts by verified email.

Still SSH-only by design, and listed as such on [[Parity]]: token
minting, account export, secrets, mirror tokens, domain claims,
repository delete and transfer, organization create/rename/delete.

** Guardrails

- PARITY page in this wiki: a maintained matrix of capability x
  surface (SSH/CLI/web/API), updated in the MR that changes it.
- Rule for new features: lands over SSH first; if it belongs to the
  triage/review/respond loop it lands on the web in the same MR.
- The view-only mode guarantee stays structural: accounts-mode routes
  never registered there.

* Phase S — security (cross-cutting)

Not a sequential phase: items land alongside whatever phase is active,
and the whole set gates flipping gitbay.org to open registration.

- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
  multi-user half
- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — concrete items done 2026-08-24
  (umbrella stays open for ongoing work). Both layers landed:
  - software: fuzz targets for every attacker-facing parser (found and
    fixed a decodeArmor slice bug), CSP + security headers, govulncheck
    in =deploy/audit.sh= (fixed circl GO-2026-4550), token comparison
    audit (hash-lookup, no Go-level compare), [[Threat-Model]],
    optional minisign over release manifests
  - host: systemd sandbox (=SystemCallFilter=@system-service=,
    =PrivateDevices=, =LockPersonality=, =MemoryDenyWriteExecute=, …),
    unattended-upgrades, fail2ban + =MaxStartups=/=MaxAuthTries= on the
    admin sshd, hourly disk/service/cert monitoring; DB file modes 0750,
    litestream noted for continuous replication. Applied to bay1.

Already true and worth preserving (the threat model will write these
down): the forge never executes repository content; no server signing
key; repo-authored HTML never renders on the forge origin; tokens and
sessions stored as hashes only; SSRF guards at registration and dial
time; private repositories indistinguishable from nonexistent.

* Explicitly not planned

Recorded so their absence reads as a decision, not an oversight:

- container/package registry — scope creep away from "forge"; external
  registries integrate via CI
- email patch flow — revisit only if sourcehut-style demand appears
- federation (ForgeFed) and Postgres — no current need at this scale

* Decisions

- **gitbay.org will eventually be open to all.** (Decided 2026-08-24.)
  Sequencing consequence: before flipping =registration = "open"=, the
  instance needs #14 (audit log, rate limiting, quotas), #9 (web
  signup), an SMTP relay configured for verification mail, and enough
  of Phase 1 that new users get a credible product. Interim step:
  invite mode for early collaborators as soon as [mail] is configured.
- **Versioning**: semver, starting at v0.1.0 on the current state.
  0.x signals moving surfaces; =protocol_version= increments only on
  breaking envelope/command changes and is otherwise decoupled from
  release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
  annotated and signed.
- **Second contributors**: invite mode is the on-ramp (their keys and
  verified emails make signed-main enforceable for them too). A
  CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
  signed commits, =go test ./...= green, review required once #19
  exists. No CLA — 0BSD needs none; sign-off optional.