Sam Jeston
History
| 1 | # Openhub documentation |
| 2 | |
| 3 | These pages explain how Openhub works inside: its components, the data they keep and the rules they follow. They are written for two readers: |
| 4 | |
| 5 | - **People** running, reviewing or extending Openhub. |
| 6 | - **Coding agents** that need accurate context before changing the system. |
| 7 | |
| 8 | Related documents: |
| 9 | |
| 10 | - The [project README](../README.md) covers installing, configuring and using Openhub. |
| 11 | - [`CLAUDE.md`](../CLAUDE.md) and [`templates/CLAUDE.md`](../templates/CLAUDE.md) cover coding conventions and pitfalls. |
| 12 | |
| 13 | These pages fill the gap between those: they explain the mechanics, so you can change the system without first reading every source file. |
| 14 | |
| 15 | ## Contents |
| 16 | |
| 17 | | Document | Read it to learn | |
| 18 | | --- | --- | |
| 19 | | [Architecture](architecture.md) | What runs in the process, how requests flow through it, and where files live on disk | |
| 20 | | [Data model](data-model.md) | The SQLite tables, the bare repositories, and the invariants that tie them together | |
| 21 | | [Accounts and access](accounts-and-access.md) | How sign-up, sessions and SSH keys work, and who may read, push to or administer a repository | |
| 22 | | [Git transport](git-transport.md) | How `git push`, `fetch` and `clone` are served over SSH and HTTP, and how archives are built | |
| 23 | | [Pull requests](pull-requests.md) | The pull request lifecycle, how heads and merge bases are tracked, and the three merge methods | |
| 24 | | [Web interface](web-interface.md) | Routes, the request pipeline, code browsing, diffs, syntax highlighting and Markdown | |
| 25 | | [Security](security.md) | The threat model, the protections in place, known gaps and hardening advice | |
| 26 | | [Operations](operations.md) | How to deploy, back up, upgrade, administer and troubleshoot an instance | |
| 27 | |
| 28 | ## Quick lookup |
| 29 | |
| 30 | | Question | Where the answer is | |
| 31 | | --- | --- | |
| 32 | | Who may do what to a repository? | [Accounts and access → Permission model](accounts-and-access.md#permission-model) (`AppState::access` in `src/state.rs`) | |
| 33 | | What happens when someone pushes? | [Git transport → After a push](git-transport.md#after-a-push) (`sync::after_push` in `src/sync.rs`) | |
| 34 | | How does Openhub notice a pull request was merged on the command line? | [Pull requests → Tracking open pull requests](pull-requests.md#tracking-open-pull-requests) | |
| 35 | | How does a web merge avoid racing a concurrent push? | [Pull requests → Merging in the web interface](pull-requests.md#merging-in-the-web-interface) | |
| 36 | | How does `/tree/feature/login/src` know where the branch name ends? | [Web interface → Refs and paths in URLs](web-interface.md#refs-and-paths-in-urls) | |
| 37 | | Where is a repository stored on disk? | [Data model → Repositories on disk](data-model.md#repositories-on-disk) | |
| 38 | | Which work uses libgit2, and which uses the `git` program? | [Architecture → libgit2 and the git executable](architecture.md#libgit2-and-the-git-executable) | |
| 39 | | How do I add a database column? | [Data model → Changing the schema](data-model.md#changing-the-schema) | |
| 40 | | Is it safe to leave sign-ups open? | [Security → Known gaps](security.md#known-gaps) | |
| 41 | | How do I make someone an administrator? | [Operations → Administration without a UI](operations.md#administration-without-a-ui) | |
| 42 | | Why does a form say "Cross-origin request rejected"? | [Operations → Troubleshooting](operations.md#troubleshooting) | |
| 43 | |
| 44 | ## Conventions in these pages |
| 45 | |
| 46 | - Code is referenced by file and function name (for example `git::merge` in `src/git.rs`), not by line number, so references survive edits. |
| 47 | - "Repository" means a hosted repository. "Bare repository" means its directory on disk. |
| 48 | - Most pages end with a **When you change this** list naming the other places that must change with it. |
| 49 | - `docs/screenshots/` holds the images embedded in the project README. [`CLAUDE.md`](../CLAUDE.md) explains when and how to retake them. |
| 50 | |
| 51 | ## Keeping these docs accurate |
| 52 | |
| 53 | These pages describe behaviour that the code implements. When a change alters something described here, update the page in the same change. If a page and the code disagree, the code is right and the page is a bug. |