README.org

  1#+title: gitbay
  2#+author: Christian Cleberg
  3
  4[[https://gitbay.org/krz/gitbay/builds][file:https://gitbay.org/krz/gitbay/badge/build.svg]]
  5
  6A CLI-first git forge. One binary, SQLite, and the system =git= — designed
  7so the command line is the product and the web UI is a rendering of state
  8the CLI already manages. Runs at [[https://gitbay.org]].
  9
 10* Design
 11
 12SSH is the API. The server authenticates by public key, then dispatches the
 13requested command: =git-upload-pack= / =git-receive-pack= stream the git
 14transport, anything else is a control command. The control plane is fully
 15usable from stock OpenSSH with no client installed:
 16
 17#+begin_src sh
 18ssh git@gitbay.org repo create you/project --private
 19ssh git@gitbay.org issue create you/project --title "bug" --file - < body.md
 20ssh git@gitbay.org repo log you/project --json
 21#+end_src
 22
 23The =gitbay= CLI is ergonomics on top — instance profiles, repo inference
 24from the origin remote, =$EDITOR= for long text — never a requirement. A
 25registry test enforces that every command stays reachable over bare ssh.
 26
 27Properties that follow from the design:
 28
 29- pushing is SSH-only. HTTPS and =git://= serve anonymous reads of public
 30  repositories; a push over HTTPS is answered with a pkt-line ERR that
 31  every git version prints as =remote error:= — no credential prompt,
 32  ever. Private repositories answer 404/not-found identically to
 33  nonexistent ones on every surface.
 34- commit signatures (OpenPGP and SSHSIG) are verified against registered
 35  keys and verified emails, with six distinct states — =verified=,
 36  =signed_unknown_key=, =signed_email_mismatch=, =signed_key_expired=,
 37  =signed_key_revoked=, =bad_signature=, =unsigned= — cached and
 38  invalidated by a global key epoch, so registering a key retroactively
 39  verifies old commits.
 40- there is no server signing key. Server-created commits (web edits,
 41  merge/squash/rebase commits) display honestly as unsigned, and branches
 42  with =require_signed_commits= accept only fast-forward merges of
 43  verified commits — enforced at push time and merge time.
 44- the web UI is server-rendered with no JavaScript required. In
 45  =view_only= mode the mutating routes are never registered on the mux;
 46  browser sessions, where enabled, are minted over SSH (=web login=) —
 47  there are no passwords.
 48
 49* Features
 50
 51- repositories with per-branch protection, forks, and organizations
 52  (shared owner namespace, membership-derived access)
 53- issues and merge requests (fast-forward, merge-commit, squash, rebase)
 54  entirely over ssh, with reviews that go stale on force-push
 55- merge request heads are fetched /into/ the target repository, so an MR
 56  survives deletion of its source fork
 57- =repo import= mirrors from any http(s)/git URL, tokens via stdin only
 58- registration modes: =closed= (admin creates users), =invite=, =open=
 59  with SMTP email verification
 60- signed outbound webhooks with retries, dead-lettering, and SSRF
 61  guarding; a JSON API (=POST /api/v1/cmd=) fronting the same command
 62  registry, with bearer tokens mintable only over SSH
 63- built-in ACME (Let's Encrypt) TLS; =admin backup= produces one
 64  restore-tested archive (database snapshot first, then repositories)
 65
 66* Server quickstart
 67
 68#+begin_src sh
 69# /etc/gitbay/config.toml
 70[server]
 71root = "/var/lib/gitbay"
 72site_url = "https://forge.example.org"
 73
 74[http]
 75acme_email = "you@example.org"
 76#+end_src
 77
 78#+begin_src sh
 79gitbayd --config /etc/gitbay/config.toml check-config
 80gitbayd --config /etc/gitbay/config.toml admin user create you \
 81    --key ~/.ssh/id_ed25519.pub --email you@example.org --verified --admin
 82gitbayd --config /etc/gitbay/config.toml serve
 83#+end_src
 84
 85The embedded SSH listener takes port 22 (move the host sshd, or set
 86=ssh.mode = "system"= to run under it via =AuthorizedKeysCommand=). See
 87=deploy/= for a cloud-init file, hardened systemd unit, and nightly
 88backup timer.
 89
 90* Client quickstart
 91
 92#+begin_src sh
 93gitbay remote add myforge forge.example.org --default
 94gitbay auth whoami
 95gitbay repo create you/project
 96gitbay repo clone you/project && cd project
 97gitbay issue create --title "first issue"   # repo inferred from origin
 98gitbay mr checkout 4                        # fetches refs/merge-requests/4/head
 99#+end_src
100
101Every read command takes =--json=; stdout is data, stderr is messages;
102exit codes are stable (0 ok, 2 usage, 3 not found, 4 denied). Man pages
103via =gitbay man=, completions via =gitbay completion <shell>=.
104
105* Documentation
106
107Docs live in [[https://gitbay.org/krz/gitbay/wiki][the wiki]], dogfooding the
108wiki feature:
109
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
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/Threat-Model][threat model]] — what the forge trusts and never does
114
115* Contributing
116
117See [[file:CONTRIBUTING.org][CONTRIBUTING]]. Development happens on gitbay.org itself.
118
119* Development
120
121#+begin_src sh
122go build ./...
123go test ./...        # e2e drives real git, ssh, sshd, and gpg binaries
124#+end_src
125
126Layout: =cmd/gitbay= (CLI), =cmd/gitbayd= (daemon, hooks, admin),
127=internal/control= (command registry — the single source of truth fronted
128by ssh and the JSON API), =internal/sshd= / =httpd= / =gitd= (transports),
129=internal/sig= (signature verification), =internal/policy= (access rules),
130=internal/store= (SQLite, migrations), =e2e/= (integration tests).
131
132* License
133
1340BSD.