krz/gitbay

Wiki: Architecture/00-Overview

Architecture/00-Overview

Architecture and security

Architecture, trust boundaries and security controls of gitbay, written for a security reviewer or auditor. Every statement about behaviour names the file, and usually the function, that implements it; statements that rest on documentation or deployment files say so. The pages track the default branch and change in the same merge request as the code they describe.

Scope

  • The gitbayd daemon, the gitbay CLI and the gitbay-runner CI runner, all in this repository.
  • The reference deployment described by deploy/ (a single Linux host, systemd, rootless podman for CI).
  • The iOS client (krz/gitbay-ios) only where it touches the server: the JSON API and push notifications.

Out of scope: the host operating system beyond the unit files and bootstrap in deploy/, the object store holding offsite backups, and Apple's push service.

Figures as of the last review

Item Value
Reviewed at 2c08460 (2026-09-27)
Schema version migration 0059
Control commands 232 registered, 79 marked ReadOnly
Go 1.27, CGO_ENABLED=0
Direct Go deps 15 (go.mod)

The command count comes from gitbay help --json on the live instance; the ReadOnly count from the ReadOnly: true literals in internal/control/.

Documents

# Document Diagram
1 System context 01-context.svg
2 Components 02-components.svg
3 Deployment and network 03-deployment.svg
4 Trust boundaries and data flows 04-trust-boundaries.svg, 06-push-flow.svg
5 Identity and access 05-authorization.svg
6 Data and cryptography
7 CI and supply chain 07-ci-flow.svg
8 Operations
9 Controls matrix
10 Known gaps

Reading order for a first pass: 1, 4, 5, 9, 10. The others are reference.

Conventions

  • Paths are relative to the repository root. For a pinned snapshot, read these pages at a tag: the wiki is part of the repository.
  • "Documented" means the statement rests on the wiki (.gitbay/wiki/) or deploy/ rather than on code.
  • Numbers such as #255 are issues on krz/gitbay; krz/gitbay-ios#15 names the other repository.
  • Diagrams are SVG with a light and a dark rendering chosen by the viewer's colour scheme. They are generated by .gitbay/wiki/Architecture/diagrams/diagrams.py; edit that and rerun it rather than the SVGs.

Checking a claim

The instance answers the same questions the documents make claims about:

gitbay help --json                 # the command registry: paths, flags, ReadOnly
curl -s https://gitbay.org/healthz # the deployed commit
curl -sI https://gitbay.org/       # security headers
ssh git@gitbay.org whoami          # identity resolution over stock OpenSSH

Related wiki pages

  • Threat-Model — the project's own threat model; this package extends it.
  • Parity — which capability is reachable from which surface.
  • Admin — configuration, backups, operations.
  • API — the JSON API.