#+title: 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 | [[file:01-System-Context.org][System context]]                    | =01-context.svg=                    |
| 2 | [[file:02-Components.org][Components]]                        | =02-components.svg=                 |
| 3 | [[file:03-Deployment.org][Deployment and network]]            | =03-deployment.svg=                 |
| 4 | [[file:04-Trust-Boundaries.org][Trust boundaries and data flows]]   | =04-trust-boundaries.svg=, =06-push-flow.svg= |
| 5 | [[file:05-Identity-and-Access.org][Identity and access]]               | =05-authorization.svg=              |
| 6 | [[file:06-Data-and-Cryptography.org][Data and cryptography]]             |                                                 |
| 7 | [[file:07-CI-and-Supply-Chain.org][CI and supply chain]]               | =07-ci-flow.svg=                    |
| 8 | [[file:08-Operations.org][Operations]]                        |                                                 |
| 9 | [[file:09-Controls.org][Controls matrix]]                   |                                                 |
| 10 | [[file:10-Known-Gaps.org][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:

#+begin_src sh
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
#+end_src

* Related wiki pages

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