Overview
GitHub is the only required integration for Nectr. The platform uses GitHub’s REST API to:- Fetch PR diffs, files, and metadata
- Retrieve issues, contributors, and repository stats
- Post review comments and verdicts
- Receive webhook events for new PRs
app/integrations/github/ (client, OAuth, webhooks)
Prerequisites
- GitHub Account (personal or organization)
- GitHub OAuth App for user authentication
- GitHub Personal Access Token (PAT) for posting reviews
Setup Guide
1. Create a GitHub OAuth App
Navigate to GitHub Settings
Go to github.com/settings/developers → OAuth Apps → New OAuth App
Configure OAuth App
- Application name:
Nectr(or your custom name) - Homepage URL:
https://your-backend.up.railway.app - Authorization callback URL:
https://your-backend.up.railway.app/auth/github/callback
2. Generate a GitHub PAT
Nectr uses a Personal Access Token to post review comments on behalf of a bot account.Go to Token Settings
github.com/settings/tokens → Generate new token (classic)
3. Set Environment Variables
Add the following to.env:
.env
4. Connect a Repository
Once Nectr is running:- Login via OAuth → Nectr exchanges the OAuth code for an access token
- Select a repository → Nectr installs a webhook automatically
- Webhook events →
pull_requestandissuesevents trigger reviews
How It Works
OAuth Flow
File:app/integrations/github/oauth.py
- User clicks “Connect with GitHub”
- Nectr redirects to GitHub OAuth (
/auth/github) - GitHub redirects back with a
codeparameter - Nectr exchanges the code for an access token:
- User’s access token is stored in the database
Webhook Installation
File:app/integrations/github/webhook_manager.py
When a user connects a repository, Nectr installs a webhook automatically:
pull_request→ Triggers review when a PR is opened or updatedissues→ (Future) Links issue context to reviews
GitHub REST API Client
File:app/integrations/github/client.py (GithubClient)
Nectr uses a custom async GitHub client built on httpx. Key methods:
- Pull Requests
- Issues
- Repository Stats
- Review Comments
Token Resolution
File:app/integrations/github/client.py:16
Nectr resolves GitHub tokens in this order:
GITHUB_PATfrom.env(production)gh auth tokenfrom GitHub CLI (local development)- Error if no token is available
Caching & Rate Limits
PR State Cache
File:app/integrations/github/client.py:76
Nectr caches PR states (open/closed/merged) to reduce GitHub API calls:
- TTL: 60 seconds for open PRs, 300 seconds for merged/closed
- Max entries: 500 (LRU eviction)
- Key format:
owner/repo#pr_number
Rate Limits
GitHub enforces rate limits:- Authenticated: 5,000 requests/hour
- Unauthenticated: 60 requests/hour
- Use PAT for all requests (included in
headers) - Cache frequently accessed data (PR state, contributor stats)
- Use GraphQL API for complex queries (future enhancement)
Troubleshooting
Error: No GitHub token available
Error: No GitHub token available
Cause: Neither
GITHUB_PAT nor gh auth token is set.Fix:- Set
GITHUB_PATin.env - Or run
gh auth login(local dev only)
Webhook not receiving events
Webhook not receiving events
Cause: Webhook URL is unreachable or secret mismatch.Fix:
- Check
BACKEND_URLin.env(must be publicly accessible) - Verify webhook secret in database matches GitHub config
- Test webhook delivery in GitHub → Settings → Webhooks → Recent Deliveries
Rate limit exceeded
Rate limit exceeded
Cause: Too many API requests in a short time.Fix:
- Use a GitHub App instead of PAT (higher rate limits)
- Enable caching for frequently accessed data
- Reduce
per_pagein list queries
OAuth callback fails
OAuth callback fails
Cause: Callback URL mismatch or missing OAuth credentials.Fix:
- Ensure
GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRETare set - Verify callback URL in GitHub OAuth App matches
BACKEND_URL/auth/github/callback
Next Steps
MCP Protocol
Understand how Nectr connects with Linear, Sentry, and Slack
Linear Integration
Pull linked issues into PR reviews
Environment Variables
Full reference of all configuration options