GitHub Integration Setup

What rkito uses GitHub for

Feature	Mechanism
Repo ingestion	App installation — reads repo file tree
Design Audit	PR webhook → triggers AI review on open/sync
Architecture manifest	App installation — commits .rkito/architecture.yaml
Org webhooks	Webhook on installation events

1. Create the GitHub App

Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App

Fill in the required fields:

Field	Value
GitHub App name	rkito (or rkito-dev for dev)
Homepage URL	https://app.yourdomain.com
Callback URL	https://api.yourdomain.com/api/v1/integrations/githubs/installations/callback
Setup URL (after installation)	https://api.yourdomain.com/api/v1/integrations/githubs/installations/callback
Redirect on update	✅ checked
Webhook → Active	✅ checked
Webhook URL	https://api.yourdomain.com/api/v1/integrations/githubs/orgwebhook
Webhook secret	Generate with: openssl rand -hex 32 (save this)

Repository permissions

Permission	Level
Contents	Read & write
Metadata	Read-only
Pull requests	Read & write
Commit statuses	Read & write

Organisation permissions

Permission	Level
Members	Read-only

Subscribe to events

Check: Pull request, Push, Installation, Installation repositories

2. Generate a private key

In your new app, scroll to Private keys → Generate a private key

A .pem file downloads automatically. Store its contents in api/.env

3. Set environment variables

Add the following to api/.env:

# GitHub App (installation flow)
GITHUB_APP_ID=123456
GITHUB_APP_SLUG=rkito
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=<32-char hex from step 1>

# GitHub OAuth (user login — separate from App)
GITHUB_CLIENT_ID=Iv1.abc123
GITHUB_CLIENT_SECRET=abc123
GITHUB_OAUTH_CALLBACK_URL=https://api.yourdomain.com/api/v1/auth/github/callback

4. URL reference

URL	Purpose
/api/v1/integrations/githubs/installations/callback	Processes OAuth code after GitHub redirects back, stores the installation
/api/v1/integrations/githubs/orgwebhook	Receives pull_request, push, installation events from GitHub
/api/v1/auth/github/callback	User login via GitHub OAuth (separate from App installation)

5. Connect from rkito

In rkito, navigate to your org → Integrations → GitHub

Click + Connect → enter your GitHub account name → click Install GitHub App

You are redirected to GitHub — click Install and select which repos to grant access to

GitHub redirects back to rkito. The new integration appears in the table.

Click Sync repos to pull your repository list into rkito.

Common errors

state mismatch on callback

Browser session expired or the installation nonce was deleted. Start the installation flow again from rkito.

Installation succeeded but no integration appears in rkito

Check that the Webhook URL and Callback URL in GitHub App settings exactly match your API domain. Check API logs for [github-install-callback] entries.

Repos list is empty after sync

Ensure the GitHub App has been installed on the repositories you want. Go to your GitHub App → Install → select repositories.