Andy Dixon
d7318acede
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).
2.6 KiB
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
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.