Permissions & events
ZAR requests the least privilege it needs to read diffs and post reviewable feedback. This page is the exact list, plus the HTTP endpoints a self-hosted instance exposes.GitHub App permissions
| Permission | Level | Why |
|---|---|---|
| Metadata | Read | Required for every GitHub App. |
| Contents | Read & write | Read code diffs and doc files; write is used only when auto-commit is enabled. |
| Pull requests | Read & write | List changed files; post review comments and docs PRs. |
| Issues | Read & write | Reply to @docagent commands; post the welcome issue. |
| Checks | Read & write | Create the docagent/ci-gate check run for the CI gate. |
| Commit statuses | Read & write | Post the zar/docs status on analyzed commits. |
Contents: write is requested so that auto-commit can work when you turn it on. With auto-commit off (the default), ZAR reads contents but only ever writes via pull requests. See Safety & guarantees.
Webhook events
| Event | Trigger | What ZAR does |
|---|---|---|
push | Commits pushed to the watched branch | Analyze the diff; propose docs. |
pull_request | opened, synchronize, ready_for_review, merge | Analyze PR changes; comment / open docs PR; run the CI gate if enabled. |
issue_comment | created | Run @docagent / /docagent commands. |
installation | App installed / removed / suspended | Onboarding and lifecycle. |
installation_repositories | Repo added to an existing install | Onboarding for the new repo. |
installation and installation_repositories are delivered to every GitHub App automatically — there’s no separate subscription checkbox. Events other than the above are acknowledged and ignored.
HTTP endpoints (self-hosted)
ZAR is a FastAPI app. The endpoints you’ll care about:| Method & path | Purpose |
|---|---|
POST /github/webhook | The webhook URL GitHub must call. Set your GitHub App’s Webhook URL to https://YOUR_DOMAIN/github/webhook. |
GET /health | JSON health/status (service, version, environment, write-commits flag). |
GET /healthz | Minimal liveness probe ({"ok": true}). |
GET /dashboard | The dashboard UI (optionally password-protected). |
GET /auth/github, GET /auth/callback | GitHub OAuth login for the dashboard. |
GET /setup, GET /setup/installed | GitHub App install wizard. |
POST /webhooks/polar | Polar billing webhook (only if billing is configured). |
The webhook router is mounted underAdmin and MCP routes exist behind their own secrets (/github, so the full public path is/github/webhook— a common mistake is to configure just/webhook.
DOCAGENT_ADMIN_TOKEN, ADMIN_SECRET, DOCAGENT_MCP_SECRET); see Environment variables.
Related
- Installation — installing with these permissions.
- Self-hosting overview — registering your own App.
- Security — webhook verification and hardening.