Commit `0942a442ef`

0942a442efd167cccafc34fdc803d8ba6bc9ed5c

parent: 3de9fea639

Verified · cmc

cmc <hello@cleberg.net> · 2026-08-25 01:21 UTC

migrate repo docs into the wiki

users/admin/api/roadmap/threat-model move from docs/ with cross-references
rewritten to wiki page links; Home links them all.

Layout: unified · split

API.org added +127

@@ -0,0 +1,127 @@
	1	#+title: gitbay API and webhooks
	2
	3	* The JSON API
	4
	5	One endpoint fronts the entire command registry — everything the SSH
	6	control plane can do, current and future, with identical semantics.
	7	Disabled by default; the instance must set:
	8
	9	#+begin_src toml
	10	[api]
	11	enabled = true
	12	#+end_src
	13
	14	** Tokens
	15
	16	Tokens are minted over SSH and only over SSH — an API token can never
	17	create further credentials.
	18
	19	#+begin_src sh
	20	gitbay auth token create --name ci [--scope full\|read] [--ttl 30d]
	21	gitbay auth token list
	22	gitbay auth token revoke ci
	23	#+end_src
	24
	25	The token (prefix =gb_=, shown exactly once) is presented as
	26	=Authorization: Bearer gb_...=. Only a hash is stored server-side.
	27	Scope =read= permits list/show/log/diff-style commands and refuses
	28	anything that modifies state. =--ttl= takes Go durations or a day
	29	suffix (=30d=); expired, revoked, and unknown tokens all answer the
	30	same 401.
	31
	32	** POST /api/v1/cmd
	33
	34	Request body:
	35	#+begin_src json
	36	{"argv": ["issue", "create", "you/project", "--title", "from CI"],
	37	"stdin": "optional body for --file - style input"}
	38	#+end_src
	39
	40	=argv= is real argv — no shell, no quoting rules. The response is the
	41	command's own JSON envelope with =exit_code= added, plus =stderr= when
	42	the command wrote diagnostics:
	43
	44	#+begin_src json
	45	{"protocol_version": 1, "exit_code": 0, "data": {"number": 7}}
	46	#+end_src
	47
	48	HTTP status maps the exit code: 0→200, 2→400, 3→404, 4→403, else 500.
	49	Commands that emit raw text rather than an envelope (=help=, =mr diff=)
	50	come wrapped as ={"output": "..."}=. Git transport commands and the
	51	token commands are refused by name.
	52
	53	#+begin_src sh
	54	curl -s -H "Authorization: Bearer $TOKEN" \
	55	-d '{"argv":["whoami"]}' https://gitbay.org/api/v1/cmd
	56
	57	printf '{"argv":["issue","create","you/project","--title","t","--file","-"],"stdin":"body\n"}' \|
	58	curl -s -H "Authorization: Bearer $TOKEN" -d @- https://gitbay.org/api/v1/cmd
	59	#+end_src
	60
	61	* Commit statuses (CI reporting)
	62
	63	CI reports results through the same command surface (over SSH or the
	64	JSON API with a full-scope token; reporting requires write access):
	65
	66	#+begin_src sh
	67	gitbay status set <owner/name> <sha> --context build --state pending
	68	gitbay status set <owner/name> <sha> --context build --state success --url https://ci.example/run/1
	69	gitbay status list <owner/name> <sha> --json # {"combined": "...", "statuses": [...]}
	70	#+end_src
	71
	72	One row per (commit, context): re-reporting updates in place. States:
	73	=pending=, =success=, =failure=, =error=; the combined state is the
	74	worst of them. Statuses appear on commit pages, MR pages, and
	75	=mr show=. With =repo settings require-checks <repo> on=, merging
	76	requires the MR head to carry statuses and all of them green. Each
	77	report also emits a =status= event to webhooks.
	78
	79	* Webhooks
	80
	81	Per-repository outbound POSTs for repository events. Managed by repo
	82	admins:
	83
	84	#+begin_src sh
	85	gitbay webhook add <url> --secret s3cret [--events push,issue.created] # default *
	86	gitbay webhook list
	87	gitbay webhook deliveries [--limit 50] # status, attempts, last error
	88	gitbay webhook redeliver <delivery-id> # requeue, including dead letters
	89	gitbay webhook remove <id>
	90	#+end_src
	91
	92	** Events
	93
	94	=push= (data: ref, old, new, forced, deleted), =issue.created=,
	95	=issue.commented=, =issue.closed=, =issue.open=, =mr.created=,
	96	=mr.merged= (data: number, sha), =repo.imported= (data: from).
	97
	98	** Delivery
	99
	100	Each event POSTs one JSON body:
	101
	102	#+begin_src json
	103	{"event": "push",
	104	"repo": "you/project",
	105	"actor": "alice",
	106	"created_at": "2026-08-24T01:00:00.000Z",
	107	"data": {"ref": "refs/heads/main", "old": "...", "new": "...",
	108	"forced": false, "deleted": false}}
	109	#+end_src
	110
	111	Headers: =X-Gitbay-Event=, =X-Gitbay-Delivery= (id), and — when the hook
	112	has a secret — =X-Gitbay-Signature-256: sha256=<hex hmac>= over the raw
	113	body. Verify before trusting:
	114
	115	#+begin_src python
	116	import hmac, hashlib
	117	expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
	118	ok = hmac.compare_digest(expected, request.headers["X-Gitbay-Signature-256"])
	119	#+end_src
	120
	121	A 2xx within 10 seconds is success. Anything else retries with
	122	exponential backoff (30s base, doubling) and dead-letters after five
	123	attempts; =webhook deliveries= shows the trail and =redeliver= revives a
	124	dead letter. Redirects are never followed, and targets resolving to
	125	loopback/private/link-local addresses are refused both at registration
	126	and again at connect time, unless the instance sets
	127	=[webhooks] allow_local=.

Admin.org added +225

@@ -0,0 +1,225 @@
	1	#+title: gitbay admin guide
	2
	3	One static binary (=gitbayd=), one SQLite file, bare repositories on
	4	disk, and the system =git=. Schema migrations run automatically on
	5	startup and on every admin command.
	6
	7	* Install
	8
	9	Build from source (=go build ./cmd/gitbayd=), install via the vanity
	10	module path (=go install gitbay.org/gitbay/cmd/gitbayd@latest=), or use
	11	a release build: =deploy/release.sh <tag>= cross-compiles reproducible
	12	linux/amd64, linux/arm64, and darwin/arm64 binaries with a SHA256SUMS
	13	manifest (CGO off, trimpath, stripped — byte-identical per commit and
	14	toolchain).
	15
	16	#+begin_src sh
	17	install -m 755 gitbayd /usr/local/bin/
	18	adduser --system --group --home /var/lib/gitbay --shell /usr/sbin/nologin gitbay
	19	install -d -o gitbay -g gitbay -m 750 /var/lib/gitbay
	20	gitbayd --config /etc/gitbay/config.toml check-config
	21	#+end_src
	22
	23	=deploy/= in the source tree has a cloud-init file, a hardened systemd
	24	unit, and a nightly backup timer. Run as the unprivileged =gitbay= user;
	25	the unit's =AmbientCapabilities=CAP_NET_BIND_SERVICE= covers ports
	26	22/80/443 without root.
	27
	28	** The SSH port decision
	29
	30	- =ssh.mode = "embedded"= (default): gitbayd itself listens, normally on
	31	22 — move the host's admin sshd to another port. Remotes read
	32	=git@host:owner/repo= with no port gymnastics.
	33	- =ssh.mode = "system"=: the host sshd owns 22 and invokes gitbayd via
	34	=AuthorizedKeysCommand=:
	35	#+begin_example
	36	AuthorizedKeysCommand /usr/local/bin/gitbayd --config /etc/gitbay/config.toml authorized-keys %t %k
	37	AuthorizedKeysCommandUser gitbay
	38	#+end_example
	39	sshd requires that binary to be root-owned and not group/world
	40	writable. Unknown keys fail authentication inside sshd, so system mode
	41	requires =registration.mode = "closed"= (check-config enforces this).
	42
	43	* Configuration reference
	44
	45	=/etc/gitbay/config.toml=. =check-config= validates and names every
	46	contradiction; =--no-host-checks= skips port/path probes.
	47
	48	** [server]
	49	- =root= (default =/var/lib/gitbay=) — repositories, database, host
	50	keys, ACME cache all live here.
	51	- =site_url= (required) — canonical =https://host=; drives ACME, clone
	52	URLs, mail links.
	53
	54	** [ssh]
	55	- =mode= — =embedded= \| =system= (above).
	56	- =port= (22) — embedded listener port.
	57	- =host_keys= — list of private key paths; empty generates an ed25519
	58	key at =<root>/ssh/host_ed25519=.
	59
	60	** [http]
	61	- =addr= (=:443=), =tls= — =acme= \| =files= \| =off=.
	62	- =acme=: certificates via TLS-ALPN-01 on the HTTPS port, cached at
	63	=<root>/acme=; =acme_email= for the CA account; =acme_http_addr=
	64	(=:80=, ="off"= to disable) adds HTTP-01 and an https redirect —
	65	failing to bind it is a warning, not fatal. Requires an =https://=
	66	site_url with a public DNS name.
	67	- =files=: =cert_file= + =key_file=.
	68	- =off=: plain HTTP — development, or behind a TLS-terminating proxy.
	69
	70	** [web]
	71	- =mode= — =view_only= (default) \| =accounts=. In view_only the mutating
	72	web routes are never registered; in accounts, browser sessions are
	73	minted over SSH (=web login=), and users with write access can create
	74	repos, comment, and make simple file edits (which commit unsigned,
	75	honestly). =password_auth= is reserved and currently rejected.
	76
	77	** [registration]
	78	- =mode= — =closed= (default) \| =invite= \| =open=. invite/open require
	79	[mail]. See the user guide for the flows.
	80
	81	** [mail]
	82	- =smtp_host= (host:port, 587 assumed), =from=, optional =smtp_user= /
	83	=smtp_pass=. STARTTLS when offered. Required for invite/open
	84	registration and self-service =email add=; in closed mode you may omit
	85	it entirely and assert addresses by hand (below).
	86
	87	** [api]
	88	- =enabled= (false) — the JSON API surface; see [[API]]. Off
	89	means no credential-bearing HTTP endpoint exists at all.
	90
	91	** [webhooks]
	92	- =allow_local= (false) — permit webhook targets on loopback/private
	93	addresses. Leave off unless you know why you need it (SSRF).
	94
	95	** [limits]
	96	- =clone_timeout= (3600s) — cap on =repo import= fetches.
	97	- =max_blob_bytes= (100MB) — cap on raw file serving over the web.
	98	- =max_asset_bytes= (512MB) — cap per uploaded release asset.
	99	- =max_pack_bytes=, =ssh_auth_rate= — reserved, not yet enforced.
	100
	101	** [git_daemon]
	102	- =enabled= (false), =port= (9418) — the anonymous =git://= listener.
	103	Serves only public repositories that additionally ran
	104	=repo settings git-daemon <repo> on=.
	105
	106	** [mirrors]
	107	- =pull_interval_minutes= (15) — how often pull mirrors fetch their
	108	upstream. Push mirrors sync shortly after each local ref update.
	109	Mirror URLs pass the same SSRF rules as webhook targets.
	110
	111	** [go_import]
	112	Vanity Go module paths, one per line: ="host/module" = "owner/repo"=.
	113	Requests with =?go-get=1= at or under the module path answer with the
	114	go-import meta tag pointing at the repository's HTTPS clone URL, so
	115	=go install host/module/cmd/...@latest= resolves. The repository should
	116	be public (the module path itself confirms it exists).
	117
	118	* Users, email, invites
	119
	120	#+begin_src sh
	121	gitbayd admin user create alice --key alice.pub --email a@example.org --verified [--admin]
	122	gitbayd admin email verify alice a@example.org # admin assertion, no SMTP needed
	123	gitbayd admin invite --email b@example.org # mails a code; prints it if no SMTP
	124	#+end_src
	125
	126	"Verified" means SMTP-confirmed or host-admin-asserted; the database
	127	records which. Verified emails are what make commit signatures
	128	meaningful — an unverified address never produces a =verified= badge.
	129
	130	* Audit and account control
	131
	132	The audit log is the security feed (events are the product feed): every
	133	successful mutating command with its argv and source credential (SSH key
	134	fingerprint or API), registrations, admin actions, force-pushes, and
	135	auth failures/throttling. Secrets never appear — they travel on stdin,
	136	never in argv.
	137
	138	#+begin_src sh
	139	gitbayd admin audit [--limit n] # host-local
	140	ssh git@<host> audit [--limit n] # instance admins, SSH only
	141	gitbayd admin user disable <name> # suspend: SSH, web, API all refused;
	142	gitbayd admin user enable <name> # sessions dropped, nothing deleted
	143	#+end_src
	144
	145	=limits.ssh_auth_rate= (10) throttles per-IP authentication failures
	146	per minute — successful auths never count and clear the slate.
	147	=limits.max_pack_bytes= is enforced as =receive.maxInputSize= on every
	148	push.
	149
	150	* Maintenance
	151
	152	#+begin_src sh
	153	gitbayd admin stats [--json] # counts, database size, per-repo disk
	154	gitbayd admin gc [--repo owner/name] # git gc: repack and prune; per-repo sizes
	155	gitbayd admin gc --aggressive # thorough repack; slow, rarely needed
	156	#+end_src
	157
	158	=deploy/cloud-init.yaml= ships a =gitbay-gc.timer= that runs =admin gc=
	159	weekly (Sunday 07:00 UTC). Imported repositories keep whatever pack
	160	layout the source sent, so a first manual =admin gc= after a bulk
	161	import is worthwhile.
	162
	163	* Backup and restore
	164
	165	#+begin_src sh
	166	gitbayd admin backup --out /var/backups/gitbay/backup.tar.gz
	167	#+end_src
	168
	169	One archive: a consistent SQLite snapshot (taken before the
	170	repositories are read, so the database never references objects the
	171	archive missed), every repository, and the SSH host keys. Excluded:
	172	hook socket, regenerated hook scripts, WAL files. Safe to run against a
	173	live daemon.
	174
	175	Restore: extract into an empty directory, point =server.root= at it,
	176	start gitbayd. Host keys are preserved, so clients keep their
	177	known_hosts entries; hooks regenerate at startup.
	178
	179	* Upgrades
	180
	181	Replace the binary, restart the unit. Migrations apply automatically and
	182	are transactional; hook scripts under =<root>/hooks= are rewritten at
	183	startup to point at the current binary path.
	184
	185	* Security
	186
	187	The [[Threat-Model]] file is the reference for what the forge
	188	trusts and refuses to do. Operational checklist:
	189
	190	- Software checks. =deploy/audit.sh= runs =go vet=, =govulncheck=
	191	(the module list is deliberately short — review it on each release),
	192	and a short fuzz pass over every attacker-facing parser (pkt-line,
	193	commit, SSHSIG armor, OpenPGP key, SSH tokenizer). Run it before
	194	tagging a release.
	195	- Web responses carry a scripts-forbidden CSP, =X-Frame-Options:
	196	DENY=, =nosniff=, =no-referrer=, and HSTS when TLS is on — no
	197	configuration needed.
	198	- Host sandboxing. The systemd unit in =deploy/cloud-init.yaml= runs
	199	gitbayd unprivileged with =ProtectSystem=strict=, =PrivateDevices=,
	200	=LockPersonality=, =MemoryDenyWriteExecute=,
	201	=SystemCallFilter=@system-service=, and =RestrictAddressFamilies= to
	202	INET/INET6/UNIX. It keeps =CAP_NET_BIND_SERVICE= only, to bind 22/80/443.
	203	- OS patches apply via =unattended-upgrades= (security origins,
	204	auto-reboot 04:30 if required).
	205	- Admin sshd (2222) is throttled by =MaxStartups=/=MaxAuthTries= and
	206	watched by =fail2ban=; gitbayd's own port 22 is throttled by
	207	=limits.ssh_auth_rate= (auth failures per IP per minute).
	208	- Monitoring. =gitbay-monitor.timer= posts disk/service/cert status
	209	hourly to the webhook URL in =/etc/gitbay/monitor.url= (create the
	210	file to enable; absent = silent). Alerts fire on a stopped service or
	211	disk ≥ 85%.
	212	- Database. =gitbay.db= and its WAL live under =/var/lib/gitbay= (mode
	213	0750, owned by =gitbay=). The nightly archive plus provider snapshots
	214	are the recovery path; for tighter RPO, add continuous replication
	215	(litestream) against the same file — it coexists with the WAL.
	216
	217	* Odds and ends
	218
	219	- deleting a fork marks MRs sourced from it =source_gone=; their diffs
	220	remain viewable and mergeable because the target repo owns the
	221	objects.
	222	- =refs/merge-requests/*= is server-owned and unpushable by clients.
	223	- audit-relevant activity (issue/MR lifecycle, imports, pushes) lands in
	224	the =events= table, which also feeds webhooks.
	225	- the daemon idles under 10MB RSS; the smallest VPS tier is adequate.

Home.org +7 −1

	@@ -4,4 +4,10 @@ CLI-first git forge: SSH is the API, the web is a rendering.
4		4
5	- [[Quickstart][Quickstart]] — clone, push, first issue	5	- [[Quickstart][Quickstart]] — clone, push, first issue
6	- [[FAQ][FAQ]] — common questions from GitHub migrants	6	- [[FAQ][FAQ]] — common questions from GitHub migrants
7	- Full guides live in the repo: [[https://gitbay.org/krz/gitbay/blob/main/docs/users.org][users]], [[https://gitbay.org/krz/gitbay/blob/main/docs/admin.org][admin]], [[https://gitbay.org/krz/gitbay/blob/main/docs/api.org][API]], [[https://gitbay.org/krz/gitbay/blob/main/docs/threat-model.org][threat model]]	7	- [[Users][User guide]] — accounts, keys, verified commits, repos, issues, MRs
		8	- [[Admin][Admin guide]] — install, configuration reference, backup, security
		9	- [[API][API and webhooks]] — the JSON API contract, tokens, payloads
		10	- [[Roadmap][Roadmap]] — status, phases, decisions, what is not planned
		11	- [[Threat-Model][Threat model]] — what the forge trusts and never does
		12
		13	This wiki is a git repository: =git clone ssh://git@gitbay.org/krz/gitbay.wiki.git=

Roadmap.org added +148

@@ -0,0 +1,148 @@
	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 (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
	64	Goal: someone who is not the author runs an instance and moves their
	65	work 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
	82	Bigger 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 — done 2026-08-25 (members-role scoping + per-repo team grants)
	90	- [[https://gitbay.org/krz/gitbay/issues/25][#25]] wikis — done 2026-08-25 (push-edited .wiki companions; krz/gitbay has one)
	91
	92	Done for the wiki half (2026-08-25): the docs now live in this wiki,
	93	dogfooding #25. When #15 (pages) lands they can graduate to a published
	94	site.
	95
	96	* Phase S — security (cross-cutting)
	97
	98	Not a sequential phase: items land alongside whatever phase is active,
	99	and the whole set gates flipping gitbay.org to open registration.
	100
	101	- [[https://gitbay.org/krz/gitbay/issues/14][#14]] audit logging, rate limiting, quotas, user disable — the
	102	multi-user half
	103	- [[https://gitbay.org/krz/gitbay/issues/28][#28]] hardening umbrella — concrete items done 2026-08-24
	104	(umbrella stays open for ongoing work). Both layers landed:
	105	- software: fuzz targets for every attacker-facing parser (found and
	106	fixed a decodeArmor slice bug), CSP + security headers, govulncheck
	107	in =deploy/audit.sh= (fixed circl GO-2026-4550), token comparison
	108	audit (hash-lookup, no Go-level compare), [[Threat-Model]],
	109	optional minisign over release manifests
	110	- host: systemd sandbox (=SystemCallFilter=@system-service=,
	111	=PrivateDevices=, =LockPersonality=, =MemoryDenyWriteExecute=, …),
	112	unattended-upgrades, fail2ban + =MaxStartups=/=MaxAuthTries= on the
	113	admin sshd, hourly disk/service/cert monitoring; DB file modes 0750,
	114	litestream noted for continuous replication. Applied to bay1.
	115
	116	Already true and worth preserving (the threat model will write these
	117	down): the forge never executes repository content; no server signing
	118	key; repo-authored HTML never renders on the forge origin; tokens and
	119	sessions stored as hashes only; SSRF guards at registration and dial
	120	time; private repositories indistinguishable from nonexistent.
	121
	122	* Explicitly not planned
	123
	124	Recorded so their absence reads as a decision, not an oversight:
	125
	126	- container/package registry — scope creep away from "forge"; external
	127	registries integrate via CI
	128	- email patch flow — revisit only if sourcehut-style demand appears
	129	- federation (ForgeFed) and Postgres — no current need at this scale
	130
	131	* Decisions
	132
	133	- gitbay.org will eventually be open to all. (Decided 2026-08-24.)
	134	Sequencing consequence: before flipping =registration = "open"=, the
	135	instance needs #14 (audit log, rate limiting, quotas), #9 (web
	136	signup), an SMTP relay configured for verification mail, and enough
	137	of Phase 1 that new users get a credible product. Interim step:
	138	invite mode for early collaborators as soon as [mail] is configured.
	139	- Versioning: semver, starting at v0.1.0 on the current state.
	140	0.x signals moving surfaces; =protocol_version= increments only on
	141	breaking envelope/command changes and is otherwise decoupled from
	142	release numbers. v1.0.0 when Phase 1 and #26 land. Tags are
	143	annotated and signed.
	144	- Second contributors: invite mode is the on-ramp (their keys and
	145	verified emails make signed-main enforceable for them too). A
	146	CONTRIBUTING file states the workflow: fork on gitbay.org, MR with
	147	signed commits, =go test ./...= green, review required once #19
	148	exists. No CLA — 0BSD needs none; sign-off optional.

Threat-Model.org added +92

@@ -0,0 +1,92 @@
	1	#+title: gitbay threat model
	2
	3	What the forge trusts, what it refuses to do, and where the boundaries
	4	are. This is the reference for security review; it complements the audit
	5	log and hardening notes in [[Admin]].
	6
	7	* What gitbay never does
	8
	9	- Execute repository content. Git object contents are never run. Hooks
	10	are gitbay's own binary, invoked by git; they compute facts and ask the
	11	daemon over a unix socket. Repo files are only ever read.
	12	- Hold a signing key. There is no server-side signing key. "Verified"
	13	means a signature made by a key the user registered — the server
	14	never vouches for a commit it did not receive already signed. Merge
	15	commits the server creates are honestly =unsigned=.
	16	- Serve repository HTML on its own origin as active content. Raw file
	17	serving is =text/plain= with =nosniff=. Rendered markdown/org is
	18	sanitized (bluemonday) and served under a CSP that forbids scripts.
	19	- Put secrets in argv, URLs, or logs. Import and mirror credentials,
	20	registration invites, and API tokens travel on stdin or in request
	21	bodies, never as command arguments (visible in =/proc=) or query
	22	strings. Tokens are stored only as SHA-256 hashes.
	23	- Confirm the existence of private repositories. Every surface answers
	24	"not found" identically for a private repo and a nonexistent one — web
	25	pages, git transport, control commands, release asset downloads.
	26
	27	* Trust boundaries
	28
	29	- SSH public key = identity. The SSH username is ignored; the presented
	30	key's fingerprint resolves to an account. Key uniqueness is global.
	31	- Per-instance trust. Email verification and key registration are local
	32	to an instance and never transfer. Account migration re-registers keys
	33	and re-verifies emails on the target by design.
	34	- The control plane is one authenticated channel (SSH), fully usable
	35	from stock OpenSSH. The JSON API fronts the same command registry with
	36	bearer tokens minted only over SSH; git transport never runs over it.
	37	- Anonymous surfaces — HTTPS clone of public repos, =git://= where
	38	enabled, the read-only web UI — carry no credentials and expose only
	39	public data. HTTP push is refused via a pkt-line =ERR=, never a 401.
	40
	41	* Attacker-controlled parsers
	42
	43	Every parser that eats bytes from a pusher, a key registrant, or an
	44	anonymous client has a fuzz target and must never panic:
	45
	46	- =internal/protocol= — the SSH command tokenizer (fuzzed against argv
	47	round-tripping).
	48	- =internal/gitd= — the =git://= pkt-line reader.
	49	- =internal/sig= — the commit parser, the SSHSIG armor decoder and blob
	50	parser, and the OpenPGP armored-key reader.
	51
	52	Run =deploy/audit.sh= to exercise them plus =go vet= and =govulncheck=.
	53
	54	* Secret handling
	55
	56	Tokens (web sessions, login links, email verification, API bearer tokens,
	57	deploy/CI) are random 256-bit values. Only their SHA-256 hash is stored,
	58	and verification is a database index lookup on that hash — the secret
	59	itself is never compared in Go, so there is no timing oracle to exploit.
	60	Webhook payloads are signed outbound with HMAC-SHA256; the forge verifies
	61	no inbound HMAC.
	62
	63	* Network-facing request forgery
	64
	65	Anything that makes the server open an outbound connection to a
	66	user-supplied address — webhook delivery, GitHub-history import
	67	=--api-base=, mirror remotes — passes the same SSRF guard: the scheme
	68	must be http/https and, unless =webhooks.allow_local= is set, the
	69	resolved address must not be loopback, private, or link-local. The
	70	webhook dialer re-checks at connect time so a DNS answer that changes
	71	after validation still cannot reach private space. Redirects are never
	72	followed.
	73
	74	* Web responses
	75
	76	Every response carries =Content-Security-Policy= (no scripts, no plugins,
	77	no embedding; inline styles allowed for chroma and label chips; images
	78	from any origin so external README images render), =X-Frame-Options:
	79	DENY=, =X-Content-Type-Options: nosniff=, =Referrer-Policy: no-referrer=,
	80	and =Strict-Transport-Security= when TLS is on. The UI needs no
	81	JavaScript, so =script-src 'none'= costs nothing.
	82
	83	* Residual risks, accepted
	84
	85	- External images in rendered READMEs load from their origin (no image
	86	proxy), which a repo author can use as a tracking pixel against a
	87	viewer. Documented; proxying is future work.
	88	- Backups are consistent per the DB-snapshot-first ordering but are not a
	89	single atomic snapshot; a few orphaned git objects are possible and
	90	harmless (see [[Admin]]).
	91	- A global signature-verification epoch over-invalidates the cache on any
	92	trust-input change. Correct, not a leak; a performance tradeoff.

Users.org added +333

@@ -0,0 +1,333 @@
	1	#+title: gitbay user guide
	2
	3	Everything here works from stock OpenSSH — replace =gitbay= with
	4	=ssh git@<host>= in any command and it behaves identically. The CLI adds
	5	convenience (instance profiles, repo inference, =$EDITOR=), nothing more.
	6	=ssh git@<host> help= lists every command the server knows.
	7
	8	* Installing the CLI
	9
	10	#+begin_src sh
	11	go install gitbay.org/gitbay/cmd/gitbay@latest # any platform with Go
	12
	13	brew tap krz/tap https://gitbay.org/krz/homebrew-tap.git
	14	brew install krz/tap/gitbay # Homebrew (macOS/Linux)
	15	#+end_src
	16
	17	Or build from source: =go build ./cmd/gitbay= in a clone of
	18	=https://gitbay.org/krz/gitbay.git=.
	19
	20	* Getting an account
	21
	22	How you join depends on the instance's registration mode. On instances
	23	with web accounts enabled, =/register= offers the same signup as a
	24	browser form (paste your SSH public key); everything below works from
	25	the terminal alone:
	26
	27	- closed :: an admin creates your account on the host and registers your
	28	first SSH key. Nothing for you to do but hand over your public key.
	29	- invite :: you receive a single-use code by email. With the SSH key you
	30	want to use:
	31	#+begin_src sh
	32	ssh git@<host> register --username you --invite <code>
	33	#+end_src
	34	Your account is active immediately; the invited address is your
	35	verified email.
	36	- open ::
	37	#+begin_src sh
	38	ssh git@<host> register --username you --email you@example.org
	39	#+end_src
	40	A verification code arrives by mail. Until you run
	41	=ssh git@<host> email verify <code>=, the account is pending: you can
	42	run =whoami= and the email commands, and nothing else — no git, no
	43	repos.
	44
	45	* SSH keys
	46
	47	Your key is your identity; there are no passwords anywhere. The SSH
	48	username is always =git= — the key alone determines who you are.
	49
	50	#+begin_src sh
	51	gitbay auth keys list
	52	gitbay auth keys add --scope git < ~/.ssh/ci_key.pub # key on stdin
	53	gitbay auth keys remove SHA256:...
	54	#+end_src
	55
	56	Scopes: =full= (default; git plus every control command) or =git= (git
	57	transport only — right for CI and automation keys, which then cannot
	58	touch issues, settings, or your account).
	59
	60	A key belongs to exactly one account instance-wide. Registering a key
	61	someone else already holds is refused without telling you whose it is.
	62
	63	* Verified commits
	64
	65	The commit badge is driven by the author email and the signing key:
	66	=verified= means the signature is valid, the key is registered to an
	67	account, and the author email is a verified address on that account.
	68
	69	For OpenPGP signing (git's default):
	70	#+begin_src sh
	71	gpg --armor --export you@example.org \| gitbay auth pgp add
	72	#+end_src
	73
	74	For SSH signing (=git config gpg.format ssh=): sign with any key
	75	registered on your account; your verified addresses act as the principal
	76	set. No separate registration step.
	77
	78	Add and verify additional addresses with =email add <address>= /
	79	=email verify <code>= (requires the instance to have SMTP; otherwise an
	80	admin can assert an address for you).
	81
	82	The states you will see, in decreasing order of trust: =verified=,
	83	=signed_unknown_key= (valid signature, key not registered here — register
	84	it and history upgrades retroactively), =signed_email_mismatch= (real
	85	key, author line claims someone else), =signed_key_expired= /
	86	=signed_key_revoked=, =bad_signature=, =unsigned=. Server-created commits
	87	(web edits, merge commits) are always =unsigned= — the server holds no
	88	signing key on principle.
	89
	90	* Repositories
	91
	92	#+begin_src sh
	93	gitbay repo create you/project [--private]
	94	gitbay repo clone you/project
	95	gitbay repo list
	96	gitbay repo show you/project
	97	gitbay repo log you/project --limit 20 # commits with signature states
	98	gitbay repo fork other/project [--name mine]
	99	gitbay repo delete you/project --yes
	100	#+end_src
	101
	102	Pushing is SSH-only. Public repositories are anonymously readable over
	103	HTTPS (and =git://= where enabled); private repositories exist only over
	104	SSH and answer "not found" to everyone without access.
	105
	106	Access and settings (owner or =admin= grant):
	107	#+begin_src sh
	108	gitbay repo access grant you/project alice write # read \| write \| admin
	109	gitbay repo access revoke you/project alice
	110	gitbay repo settings protect you/project main # no force-push, no delete
	111	gitbay repo settings require-signed you/project on # every commit must verify
	112	gitbay repo settings git-daemon you/project on # expose over git://
	113	gitbay repo topics add you/project cli forge # free-form tags, shown on the web
	114	gitbay repo search forge # find repos by name/description/topic
	115	gitbay repo grep you/project "some string" # literal git grep over the default branch
	116	gitbay repo pin you/project # pin to your web dashboard
	117	gitbay repo unpin you/project
	118	gitbay repo archive you/project # read-only: pushes and issue/MR
	119	gitbay repo unarchive you/project # writes refused, browsing intact
	120	#+end_src
	121
	122	Import from another forge — git data first, then optionally the GitHub
	123	issue and PR history (issues keep state/labels/comments; PRs land as
	124	closed or merged MRs with their discussion; originals are attributed
	125	inline since foreign authors have no local account; re-running resumes
	126	where it stopped):
	127	#+begin_src sh
	128	gitbay repo import you/mirror --from https://github.com/you/repo.git \
	129	[--private] [--token-stdin] # token on stdin, never in the URL
	130	gitbay repo import-issues you/mirror --from you/repo --token-stdin
	131	#+end_src
	132
	133	Moving between gitbay instances (no lock-in): run on the TARGET, with
	134	your key registered on both sides. Profile, repos with settings,
	135	issues, MRs, and comments replay with attribution; git data mirrors
	136	client-side through your own key. Keys never transfer and emails
	137	arrive unverified — trust is per-instance. Re-running resumes.
	138	Push-blocking policies (require-signed, protected branches) are
	139	deferred and printed for you to re-apply after the data lands.
	140	=gitbay auth export= alone doubles as a user-level backup.
	141
	142	#+begin_src sh
	143	gitbay migrate --from old-instance.example [--from-port 22]
	144	#+end_src
	145
	146	Mirroring keeps a foreign remote in sync during a gradual migration
	147	(repo admin; https remotes; the token is stored server-side for the
	148	recurring sync and never echoed back):
	149
	150	#+begin_src sh
	151	gitbay repo mirror add you/project https://github.com/you/project.git \
	152	--direction push --token-stdin # propagate after every local push
	153	gitbay repo mirror add you/copy https://github.com/them/theirs.git \
	154	--direction pull # follow upstream; local pushes refused
	155	gitbay repo mirror list # sync status and last error, per mirror
	156	gitbay repo mirror sync / remove <id>
	157	#+end_src
	158
	159	* Organizations
	160
	161	Orgs share the owner namespace with users and own repositories at
	162	=org/repo=. By default members get write on all org repos; org admins
	163	get repo admin, create repos under the org, and manage membership.
	164
	165	#+begin_src sh
	166	gitbay org create krz
	167	gitbay org members add krz alice [--role admin]
	168	gitbay org show krz
	169	gitbay org rename krz newname # clone URLs change
	170	gitbay org delete krz --yes # only when it owns no repositories
	171	#+end_src
	172
	173	Large orgs scope access with teams: set what plain membership implies,
	174	then grant per-repo roles through named teams (org admins always keep
	175	admin; the default =write= keeps the simple model):
	176
	177	#+begin_src sh
	178	gitbay org settings members-role krz none # write \| read \| none
	179	gitbay org team create krz core-devs
	180	gitbay org team add krz core-devs alice bob # org members only
	181	gitbay org team grant krz core-devs krz/gitbay write
	182	gitbay org team show krz core-devs # members + grants
	183	gitbay org team revoke / remove / delete ...
	184	#+end_src
	185
	186	* Issues
	187
	188	Anyone who can read a repository can file and comment. Closing/reopening
	189	is for the author or anyone with write; labels and assignees need write.
	190
	191	#+begin_src sh
	192	gitbay issue create --title "it breaks" [--body "..." \| --file -]
	193	gitbay issue list [--state open\|closed\|all]
	194	gitbay issue show 4
	195	gitbay issue comment 4 --message "same here"
	196	gitbay issue edit 4 --title "better title" [--body\|--file -] # author or write
	197	gitbay issue close 4 / reopen 4
	198	gitbay issue label 4 --add bug --remove wontfix
	199	gitbay issue assign 4 --add alice
	200	gitbay issue milestone 4 v1.0 # or "none" to clear
	201	#+end_src
	202
	203	Inside a clone, the repository is inferred from the =origin= remote —
	204	that is why no =owner/name= appears above. Anywhere else, pass it as the
	205	first argument. Long text: =--body= inline, =--file -= from stdin, or
	206	neither on a terminal and =$EDITOR= opens.
	207
	208	Wikis are companion repositories edited by push — no separate storage,
	209	no web editor, the same rendering pipeline as READMEs (markdown and
	210	org). Access mirrors the parent repo (read to view, write to push);
	211	the companion is created on your first push and follows the repo
	212	through transfer and delete:
	213
	214	#+begin_src sh
	215	git clone ssh://git@<host>/you/project.wiki.git
	216	# add Home.md (or .org), more pages, images; relative links between
	217	# pages just work on the web at /you/project/wiki
	218	git push
	219	#+end_src
	220
	221	Releases anchor notes and binary assets to a pushed tag (write access;
	222	assets stream over SSH, capped by the instance's =max_asset_bytes=):
	223
	224	#+begin_src sh
	225	gitbay release create v1.0 --title "First light" [--notes\|--file -\|$EDITOR]
	226	gitbay release asset add v1.0 tool-linux-amd64 < dist/tool-linux-amd64
	227	gitbay release asset get v1.0 tool-linux-amd64 > tool # or the web download link
	228	gitbay release list / show v1.0 / delete v1.0 --yes
	229	#+end_src
	230
	231	The web shows them under the repository's =releases= tab with rendered
	232	notes, sha256 sums, and download links.
	233
	234	Commit messages act on issues when the commits land on the default
	235	branch (direct push or MR merge): =closes/fixes/resolves #4= closes the
	236	issue with a linking comment, and a bare =#4= leaves a reference
	237	comment. Each issue/commit pair acts once, ever. Same repository only.
	238
	239	Milestones group issues and MRs toward a release (write access to
	240	manage, attach with =issue milestone= / =mr milestone=; progress shows
	241	on the web at =/owner/name/milestones=):
	242
	243	#+begin_src sh
	244	gitbay milestone create v1.0 --description "first release" --due 2027-01-01
	245	gitbay milestone list [--state open\|closed\|all]
	246	gitbay milestone close v1.0 / reopen v1.0
	247	#+end_src
	248
	249	Issue templates: commit =.gitbay/issue-template.md= (and optional
	250	=issue-template-<name>.md= variants) to the default branch. =gitbay
	251	issue create= prefills =$EDITOR= with the default template, the web
	252	form prefills its textarea, and =gitbay issue templates= lists them.
	253
	254	* Merge requests
	255
	256	#+begin_src sh
	257	gitbay mr create --source feature --target main --title "add thing"
	258	gitbay mr create other/upstream --source you/fork:feature --target main --title "..."
	259	gitbay mr list / show 4 / diff 4
	260	gitbay mr checkout 4 # local branch mr/4 from the MR head
	261	gitbay mr review 4 --approve # or --request-changes / --comment
	262	gitbay mr merge 4 [--strategy ff\|merge\|squash\|rebase]
	263	gitbay mr close 4
	264	#+end_src
	265
	266	Semantics worth knowing:
	267
	268	- the MR head lives in the target repository as
	269	=refs/merge-requests/N/head= (fetchable by any reader), so an MR
	270	survives deletion of its source branch or fork.
	271	- force-pushing the source updates the MR and marks existing reviews
	272	stale.
	273	- default strategy: fast-forward when possible, else a merge commit.
	274	Squash makes one commit authored by the MR author, committed by the
	275	merger. Rebase replays a linear range preserving authors; it refuses
	276	ranges containing merge commits, and when fast-forward is possible it
	277	is one (original commits and signatures land untouched).
	278	- on =require_signed_commits= branches only fast-forwards of fully
	279	verified commits merge; everything server-created is refused with
	280	instructions to rebase locally.
	281
	282	Repo admins can gate merges (=repo settings ...=): =require-approvals
	283	<n>= (fresh, non-author approvals; each reviewer's latest review is
	284	their stance, and a fresh request-changes blocks), =require-resolved=
	285	(no open review threads), =require-checks= (all statuses green). With
	286	approvals required, a =CODEOWNERS= file on the target branch (root or
	287	=.gitbay/=) additionally demands an approval from an owner of every
	288	owned changed file — gitignore-style patterns, last match wins.
	289
	290	Review threads anchor to diff lines:
	291
	292	#+begin_src sh
	293	gitbay mr diff-comment 4 --path main.go --line 12 --message "use log here"
	294	gitbay mr diff-comment 4 --reply 7 --message "done" # join thread 7
	295	gitbay mr threads 4 # threads with staleness
	296	gitbay mr resolve 4 7 / unresolve 4 7
	297	#+end_src
	298
	299	Threads render inline on the MR page. A force-push marks them stale
	300	(shown under "threads on earlier revisions") rather than guessing new
	301	anchors; =mr show= reports the unresolved count. Resolving is for the
	302	thread author, the MR author, or anyone with write.
	303
	304	* Notifications
	305
	306	When the instance has SMTP configured, activity mails you: someone
	307	opens an issue or MR on your repository, comments where you are a
	308	participant (author, commenter, reviewer), reviews, closes, or merges.
	309	You are never mailed about your own actions, and only verified primary
	310	addresses receive anything. Delivery retries on relay failure.
	311
	312	* Scripting
	313
	314	Every read command takes =--json= and emits one envelope:
	315	={"protocol_version": 1, "data": ...}=. stdout is data, stderr is
	316	messages. Exit codes are stable: 0 ok, 1 failure, 2 usage, 3 not found,
	317	4 denied, 5 server/protocol error. Nothing ever prompts; destructive
	318	commands take =--yes=.
	319
	320	For HTTP automation see [[API]].
	321
	322	* CLI setup
	323
	324	#+begin_src sh
	325	gitbay remote add myforge forge.example.org [--port n] [--user u] --default
	326	gitbay remote list
	327	gitbay init [name] [--private] # git init + repo create + origin, in one step
	328	#+end_src
	329
	330	Configuration lives at =~/.config/gitbay/config.toml=. The CLI shells
	331	out to your real =ssh=, so =~/.ssh/config=, the agent, and hardware keys
	332	all apply. Man pages: =gitbay man --dir <dir>=; completions:
	333	=gitbay completion bash\|zsh\|fish=.

Commit 0942a442ef

Commit `0942a442ef`