Create the GitHub App

Every Metis deployment runs as its own GitHub App. The app receives pull request webhooks, lets users sign in, and gives Metis scoped access to the repositories it is installed on.

1. Start a new app

   Open github.com/settings/apps/new, or go to Settings → Developer settings → GitHub Apps → New GitHub App. To create the app under an organization, use that organization's settings instead.

2. Basic information

   Field	Value
   GitHub App name	Any unique name, e.g. “Metis Reviewer (Acme)”. Reviews are posted under it.
   Homepage URL	Your dashboard URL, e.g. http://localhost:5173
   Callback URL	<FRONTEND_URL>/auth/callback, e.g. http://localhost:5173/auth/callback
   Expire user authorization tokens	Leave the default.
   Request user authorization (OAuth) during installation	Leave unchecked.

3. Webhook

   Check Active. Set the Webhook URL to https://<your-api-host>/webhooks/github. If you don't have a public URL yet, enter a placeholder and update it once your tunnel or server is up.

   Generate a random webhook secret and paste it into the Webhook secret field:

   bashCopy

   openssl rand -hex 32

   Save the same value as GITHUB_WEBHOOK_SECRET. Metis rejects any delivery whose HMAC-SHA256 signature doesn't match it.

4. Repository permissions

   Permission	Access	Used for
   Contents	Read and write	Cloning code into the sandbox; pushing branches for Issue → PR
   Pull requests	Read and write	Reading diffs, posting reviews and inline comments, updating titles and descriptions, opening PRs
   Issues	Read-only	Listing issues and loading their details for coding agents
   Metadata	Read-only	Mandatory for all GitHub Apps

   Leave every other permission at “No access”.

5. Subscribe to events

   Check Pull request. Metis acts on the opened, reopened, and synchronize actions. Other events are acknowledged and ignored.

6. Choose where it can be installed

   Only on this account is the right choice for a private deployment. Choose Any account only if other people or organizations will install your instance.

   Click Create GitHub App.

7. Collect the credentials

   On the app's settings page:

   • Copy the App ID and the Client ID.
   • Under Client secrets, click Generate a new client secret and copy it. It is shown only once.
   • Under Private keys, click Generate a private key. A .pem file downloads.

8. Install the app

   Click Install App in the sidebar, choose the account or organization, and select the repositories Metis may access. Installing the app doesn't start reviews by itself. You also need to enable each repository in the Metis dashboard.

Map the values to environment variables

How Metis uses the app

• As the app: Metis signs a short-lived JWT with your private key and exchanges it for an installation token. It uses that token to read diffs, clone code, and post reviews.
• On behalf of a user: “Login with GitHub” uses the app's OAuth flow. Metis uses the resulting token to find the installations and repositories a user can access. The token is encrypted at rest with your ENCRYPTION_KEY.

Next: fill in the rest of your environment in the configuration reference.