Documentation

GitHub App

Configure GitHub permissions, webhooks, and dashboard sign-in.

On this page

Create an app through setup

The quickstart uses GitHub App manifests. CroCode creates the app with the required permissions and saves its credentials in the shared config volume.

The setup link requires a random token from the dashboard logs. Setup consumes that token after it saves the app. Environment variables take priority over saved values.

GitHub has no app-logo API. Upload the CroCode app logo in the app settings.

Configure an app by hand

Open GitHub Settings → Developer settings → GitHub Apps → New GitHub App.
Choose a unique name. Set the homepage to your public site or the project repository.
Set the OAuth callback to https://YOUR_HOST/api/auth/callback/github. Use your actual host.
Enable the webhook at https://YOUR_HOST/webhooks/github. Keep SSL verification enabled.
Generate a webhook secret with openssl rand -hex 32. Save it in GitHub and as GITHUB_WEBHOOK_SECRET in the backend environment.
Set the permissions below. Subscribe to Pull request events. GitHub sends installation events by default.
Create the app. Save its numeric App ID as GITHUB_APP_ID. Generate a private key.
Install the app on selected repositories.

Required permissions

Permission	Access	Purpose
Repository contents	Read-only	Read code and base-commit config.
Pull requests	Read and write	Read diffs and publish COMMENT reviews.
Dependabot alerts	Read-only	Read open dependency alerts in the dashboard.
Repository metadata	Read-only	Identify repositories. GitHub includes this permission.
Organization members	Read-only	Check installation admin rights in the dashboard.

The API and worker need the App ID, webhook secret, and private key. Put the PEM contents in GITHUB_PRIVATE_KEY with literal \n between lines. You can instead mount a read-only PEM file in both services and set GITHUB_PRIVATE_KEY_PATH.

The dashboard needs its own environment file. Copy web/.env.example to web/.env for Compose. Set its GitHub client ID, client secret, app slug, auth secret, and public URL. Compose supplies the API URL.

For an existing App, add read-only Dependabot alerts access in Permissions & events. Approve the change for each installation. Enable Dependabot alerts on the repositories. The signed-in user must also have access to security alerts. The Vulnerabilities tab shows open alerts, grouped by repository. It shows access failures separately from empty results. Use the filters to search CVE IDs, packages, repositories, severity, dependency scope, and patch availability on the current page. Security coverage shows alert access, the latest attempt, and the last successful read. Success history resets when the API restarts. It does not confirm that dependency scanning is enabled. Choose Fix priority queue to rank matching alerts by severity, then known EPSS probability, then patch availability. Unknown scores stay unknown. Ranks apply to the current repository page.

Keep user token expiration enabled. The dashboard uses GitHub App user access tokens. It does not need the email permission.

Check webhook delivery

Use the webhook delivery view in GitHub App settings. A signed ping returns 202 with pong. An invalid signature returns 401. A repeat of an accepted delivery ID returns 200 with duplicate delivery.

See the full manual setup reference for key storage and account options.