Wiki: Architecture/01-System-Context
System context
What gitbay is
A self-hosted git forge: repositories, issues, merge requests, reviews,
CI, releases, wikis, snippets and notifications. One Go binary
(gitbayd), one SQLite database, and the system git binary for all
repository operations.
The design rule that shapes everything else: SSH is the API. Every
operation is a control command in one registry
(internal/control/control.go). Stock OpenSSH reaches all of them; the
CLI, the web UI and the JSON API are clients of the same registry and
do not reimplement logic (internal/httpd/control.go,
internal/httpd/api.go).
Actors
| Actor | Reaches gitbay through | Authenticates with |
|---|---|---|
| Anonymous visitor | HTTPS pages, smart HTTP fetch, git:// if on | nothing |
| Registered user | SSH (CLI or stock OpenSSH), HTTPS web, API | SSH key; web session; API token |
| Instance administrator | same as a user, plus host shell | SSH key with admin account; root |
| Deploy key holder | SSH git transport for one repository | SSH key bound to that repository |
| CI runner | SSH, runner commands and clone |
SSH key with runner scope |
| iOS app | JSON API over HTTPS; receives APNs pushes | API token pasted at sign-in |
| Webhook receiver | receives HTTPS POSTs from gitbay | verifies HMAC-SHA256 signature |
External systems
| System | Direction | Purpose | Code |
|---|---|---|---|
| ACME CA (Let's Encrypt) | out | TLS certificates | cmd/gitbayd/main.go |
| SMTP relay | out | verification, login links, notifications | internal/mail/mail.go |
| Apple Push Notification | out | iOS notifications | internal/push/apns.go |
| IMAP mailbox | out | replies to notification mail (opt-in) | internal/mailin, internal/imapc |
| Webhook endpoints | out | event delivery, user-configured | internal/webhook/webhook.go |
| Mirror remotes | out / in | push and pull mirrors, user-configured | internal/mirror/mirror.go |
| Package registries | out | dependency update checks (opt-in per repo) | internal/deps/registry.go |
| Offsite object storage | out | restic backups (host timer, not gitbayd) | documented: Admin wiki |
gitbayd makes no other outbound connection: no telemetry or update check.
Instance modes that change the attack surface
| Setting | Default | Effect |
|---|---|---|
web.mode |
view_only | accounts adds login, settings and every web write route (routes.go) |
api.enabled |
false | when false there is no credential-bearing HTTP surface |
registration.mode |
closed | open admits unknown SSH keys to register; invite needs a code |
git_daemon.enabled |
false | anonymous git:// on 9418 |
push.enabled |
false | APNs worker and device registration |
http.tls |
acme | files or off; off also drops HSTS and the cookie Secure flag |
webhooks.allow_local |
false | when false, webhook and mirror URLs may not resolve to private or loopback addresses |
gitbay.org runs with web.mode = accounts, the API enabled and
registration.mode = open, all three observable from outside (/login,
/register, /api/v1/read answering 401).