Write full documentation with screenshots

README covers what CodeNavigator is, screenshots of each view, quick start, configuration, keyboard shortcuts and links to docs/: a city guide (what every visual means, getting around), architecture (indexer, sessions, GitHub, rendering passes, routing), the HTTP API, GitHub App setup including the alert permissions, deployment (Docker, systemd, nginx, limits, security notes) and development (tests, layout, conventions, design notes).
2026-08-09 10:15:59 +01:00
parent 3b4f1505d1
commit d7318acede
13 changed files with 635 additions and 62 deletions
@@ -0,0 +1,65 @@
+# GitHub App setup
+
+Public repositories work without any setup. A GitHub App adds two things:
+
+- **Private repositories**: visitors sign in and can open repositories the app is installed on and
+  they have access to.
+- **Security alerts**: files with open code scanning or Dependabot alerts burn in the city.
+
+CodeNavigator uses the app's *user authorisation* only: no private key, no webhooks, and tokens act
+with the visitor's own permissions.
+
+## 1. Register the app
+
+Go to **https://github.com/settings/apps/new** (or an organisation's Developer settings) and fill in:
+
+| Field | Value |
+|---|---|
+| GitHub App name | anything; it becomes the slug in `github.com/apps/<slug>` |
+| Homepage URL | `https://your-host` |
+| Callback URL | `https://your-host/api/github/callback` |
+| Expire user authorization tokens | ✅ |
+| Request user authorization (OAuth) during installation | ☐ off |
+| Enable Device Flow | ☐ off |
+| Setup URL | `https://your-host/`, with **Redirect on update** ✅ |
+| Webhook → Active | ☐ off |
+| Where can this GitHub App be installed? | **Any account** to let others use it |
+
+**Repository permissions** (everything else "No access"):
+
+| Permission | Access | Needed for |
+|---|---|---|
+| Contents | Read-only | Cloning private repositories |
+| Metadata | Read-only | Added automatically |
+| Code scanning alerts | Read-only | Red tape and fire |
+| Dependabot alerts | Read-only | Yellow tape and fire |
+
+Create the app, copy the **Client ID**, and click **Generate a new client secret**.
+
+## 2. Configure the server
+
+```bash
+GITHUB_CLIENT_ID=Iv23li...
+GITHUB_CLIENT_SECRET=...
+GITHUB_APP_SLUG=your-app-slug
+```
+
+Restart the server. `GET /api/github/status` should now report `"configured": true`.
+
+## 3. Install it
+
+Visit `https://github.com/apps/<slug>`, click **Install**, and choose the repositories it may read.
+Each user (or organisation admin) installs it for their own repositories. When a signed-in visitor
+opens a repository the app can't see, CodeNavigator offers a **Grant repository access** button
+linking to that page.
+
+## How sign-in behaves
+
+- A private repo that fails to clone shows **Sign in with GitHub**. After approving on GitHub,
+  visitors land back on the site with the Open codebase dialog already showing the result and the
+  repository filled in.
+- Tokens live only in server memory for 8 hours and are never sent to the browser. Restarting the
+  server signs everyone out.
+- **Adding permissions later** (e.g. alerts): existing installations must accept the new permissions
+  on GitHub, and visitors need to sign out and back in to get a token with them. Until then the
+  sidebar reports which alert kinds it has no access to.