GitHub App Setup

GitHub App Setup

Themis authenticates to GitHub via a GitHub App called Themis AI Agent. One app registration covers every space on the deployment; each space installs the same app and receives its own installation_id.

Why a GitHub App (and not a PAT)

No dedicated bot seat on private orgs.
Per-installation rate limits (5k/hour per install, not per bot account).
Fine-grained repo permissions; org admins install once for the whole team.
Webhook delivery is bundled with the app, not wired up per repo.

Registering the App

Basic information

Name: Themis AI Agent
Homepage URL: your deployment URL (e.g. https://3coms.dev)
Where can this GitHub App be installed: Any account

Identifying and authorizing users

Callback URL: https://<your-deployment>/github_app/oauth/callback
☑️ Request user authorization (OAuth) during installation
☑️ Expire user authorization tokens
☐ Enable Device Flow

Post installation

Setup URL: leave blank (disabled when OAuth-during-install is enabled)
☑️ Redirect on update

Webhook

☑️ Active
URL: https://<your-deployment>/webhooks/github
Secret: generate a random hex string — you’ll store it in Rails credentials

Repository permissions

Permission	Level	Reason
Contents	Read & write	Code generation commits
Pull requests	Read & write	Reviews, inline comments, PR creation
Issues	Read & write	Sentry → issue, comments
Checks	Read	CI status
Commit statuses	Read	Legacy CI status
Actions	Read	Workflow run results
Workflows	Read & write	Pushing `.github/workflows/*` changes
Metadata	Read	Auto-granted

Organization permissions

Permission	Level
Members	Read

Account permissions (user-to-server OAuth)

Permission	Level
Email addresses	Read

Subscribed events

Pull request, Pull request review, Pull request review comment, Issue comment, Issues, Push, Check run, Check suite, Workflow run, Release, Installation target.

After creating the app, generate a private key from the app settings page and download the .pem file.

Storing Credentials

Add to your encrypted credentials:

bin/rails credentials:edit --environment=production

github_app:
  app_id: <integer from app page>
  client_id: <string from app page>
  client_secret: <string from app page>
  webhook_secret: <the random hex you set on the webhook>
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

If your app slug differs from the default themis-ai-agent (e.g. you named it differently), also add:

github_app:
  app_slug: <your-slug>

Restart the Rails server after updating credentials.

Installing in a Space

Space owners/managers self-install:

Open Space Settings → Connections → GitHub.
Click Install GitHub App.
On GitHub, pick the personal account or organization. For orgs, one admin install covers everyone.
GitHub redirects back to Themis — the installation ID is bound to the space.

The same user can have separate “personal” and “work” spaces, each with its own installation.

Webhook Flow

GitHub signs every delivery with the app-level webhook_secret. Themis verifies the HMAC, reads installation.id from the payload, and resolves the space via the unique github_installation_id column on space_channels.

Token Lifecycle

Themis mints installation access tokens on demand. They last one hour; Themis caches for 55 minutes and refreshes transparently. Tokens never touch the database — only the installation ID does.

Troubleshooting

“GitHub App is not configured on this deployment” — credentials missing or malformed. Double-check the YAML indentation on private_key (the | literal block is required).

Webhooks return 401 — the app-level webhook_secret in credentials doesn’t match the secret you set on the app registration.

Webhooks return No space bound to installation <id> — the space disconnected but GitHub still has the app installed. Reinstall from Space Settings, or uninstall on GitHub at https://github.com/settings/installations.