.gitbay/wiki/Architecture/00-Overview.org

 1#+title: Architecture and security
 2
 3Architecture, trust boundaries and security controls of gitbay, written
 4for a security reviewer or auditor. Every statement about behaviour
 5names the file, and usually the function, that implements it;
 6statements that rest on documentation or deployment files say so. The
 7pages track the default branch and change in the same merge request as
 8the code they describe.
 9
10* Scope
11
12- The =gitbayd= daemon, the =gitbay= CLI and the =gitbay-runner= CI
13  runner, all in this repository.
14- The reference deployment described by =deploy/= (a single Linux
15  host, systemd, rootless podman for CI).
16- The iOS client (krz/gitbay-ios) only where it touches the server: the
17  JSON API and push notifications.
18
19Out of scope: the host operating system beyond the unit files and
20bootstrap in =deploy/=, the object store holding offsite backups, and
21Apple's push service.
22
23* Figures as of the last review
24
25| Item             | Value                                              |
26|------------------+----------------------------------------------------|
27| Reviewed at      | =2c08460= (2026-09-27)                             |
28| Schema version   | migration 0059                                     |
29| Control commands | 232 registered, 79 marked =ReadOnly=               |
30| Go               | 1.27, =CGO_ENABLED=0=                              |
31| Direct Go deps   | 15 (=go.mod=)                                      |
32
33The command count comes from =gitbay help --json= on the live instance;
34the =ReadOnly= count from the =ReadOnly: true= literals in
35=internal/control/=.
36
37* Documents
38
39| # | Document                                           | Diagram                                         |
40|---+----------------------------------------------------+-------------------------------------------------|
41| 1 | [[file:01-System-Context.org][System context]]                    | =01-context.svg=                    |
42| 2 | [[file:02-Components.org][Components]]                        | =02-components.svg=                 |
43| 3 | [[file:03-Deployment.org][Deployment and network]]            | =03-deployment.svg=                 |
44| 4 | [[file:04-Trust-Boundaries.org][Trust boundaries and data flows]]   | =04-trust-boundaries.svg=, =06-push-flow.svg= |
45| 5 | [[file:05-Identity-and-Access.org][Identity and access]]               | =05-authorization.svg=              |
46| 6 | [[file:06-Data-and-Cryptography.org][Data and cryptography]]             |                                                 |
47| 7 | [[file:07-CI-and-Supply-Chain.org][CI and supply chain]]               | =07-ci-flow.svg=                    |
48| 8 | [[file:08-Operations.org][Operations]]                        |                                                 |
49| 9 | [[file:09-Controls.org][Controls matrix]]                   |                                                 |
50| 10 | [[file:10-Known-Gaps.org][Known gaps]]                        |                                                 |
51
52Reading order for a first pass: 1, 4, 5, 9, 10. The others are
53reference.
54
55* Conventions
56
57- Paths are relative to the repository root. For a pinned snapshot,
58  read these pages at a tag: the wiki is part of the repository.
59- "Documented" means the statement rests on the wiki
60  (=.gitbay/wiki/=) or =deploy/= rather than on code.
61- Numbers such as =#255= are issues on krz/gitbay; =krz/gitbay-ios#15=
62  names the other repository.
63- Diagrams are SVG with a light and a dark rendering chosen by the
64  viewer's colour scheme. They are generated by
65  =.gitbay/wiki/Architecture/diagrams/diagrams.py=; edit that and rerun
66  it rather than the SVGs.
67
68* Checking a claim
69
70The instance answers the same questions the documents make claims
71about:
72
73#+begin_src sh
74gitbay help --json                 # the command registry: paths, flags, ReadOnly
75curl -s https://gitbay.org/healthz # the deployed commit
76curl -sI https://gitbay.org/       # security headers
77ssh git@gitbay.org whoami          # identity resolution over stock OpenSSH
78#+end_src
79
80* Related wiki pages
81
82- [[file:../Threat-Model.org][Threat-Model]] — the project's own threat model; this package extends it.
83- [[file:../Parity.org][Parity]] — which capability is reachable from which surface.
84- [[file:../Admin.org][Admin]] — configuration, backups, operations.
85- [[file:../API.org][API]] — the JSON API.