GitHub API Integration Client
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub API Integration Client is a centralized module responsible for all interactions between the AI Reviewer system and the GitHub platform. Its primary purpose is to abstract the complexities of GitHub App authentication, webhook verification, and API consumption (such as Pull Request management and review posting) into a unified internal interface.
This client ensures that the system respects GitHub's rate limits, manages short-lived installation tokens, and securely verifies incoming webhook signatures. By centralizing these concerns, the architecture prevents direct SDK dependencies or raw fetch calls from leaking into the core business logic or background worker processes.
Sources: packages/github/README.md:3-9, README.md:126-133
Core Architecture and Responsibilities
The integration is structured into three distinct functional areas: Authentication/OAuth, Webhook Handling, and the Review API.
Component Overview
| Component | Responsibility | File Reference |
|---|---|---|
GitHubAppClient | Manages per-installation Octokit clients, JWT signing, and token rotation. | app-client.ts |
Webhook Verifier | Performs HMAC-SHA256 signature verification for incoming payloads. | webhook-verifier.ts |
Review Client | Specialized functions for PR file listing, metadata fetching, and review creation. | review-client.ts |
OAuth Flow | Handles user sign-in, code exchange, and profile fetching. | oauth.ts, users.ts |
Sources: packages/github/src/index.ts:3-23, packages/github/README.md:12-22
Authentication Flow
The system authenticates as a GitHub App. It generates short-lived installation tokens (valid for 1 hour) using a private key (PEM). These tokens are minted on-demand for specific installations and cached to optimize performance and rate-limit accounting.
Webhook Handling and Security
All incoming events from GitHub (e.g., pull_request, push) enter via a dedicated route that performs strict security validation before any processing occurs.
Signature Verification
The system uses HMAC-SHA256 verification via verifyGithubSignature. This involves computing the HMAC of the raw request body using a shared secret and comparing it to the X-Hub-Signature-256 header using timingSafeEqual to prevent timing attacks.
Idempotency and Deduplication
To handle GitHub's potential re-deliveries, every webhook is logged in the WebhookDelivery table. The deliveryId (from X-GitHub-Delivery) is unique; if a delivery is already marked as processedAt, the system acknowledges the request without re-triggering the background job.
Sources: apps/web/app/api/webhooks/github/route.ts:88-100, README.md:120-125
Review Client Operations
The review-client provides high-level abstractions for the AI review pipeline, specifically targeting Pull Request interactions.
Pull Request Management
The client supports fetching PR metadata and listing files. File listing includes automatic pagination, as GitHub limits responses to 100 files per page but allows up to 3000 files per PR.
Key functions include:
getPRMetadata: Fetches title, body, head SHA, and author login.listPRFiles: Aggregates all changed files, including status (added, removed, modified) and the unified diff patch.
Sources: packages/github/src/review-client.ts:60-95, packages/github/src/review-client.ts:175-204
Posting Reviews and Comments
The system utilizes the modern line and side (LEFT/RIGHT) API for review comments, rather than the deprecated integer-based position.
Technical Constraints for Reviews:
- Mode: The client is primarily configured for
COMMENTmode, which annotates the PR without blocking merges. - Truncation: Individual comment bodies are capped at approximately 65,000 bytes to stay within GitHub's character limits.
- Unified Diff: The review orchestrator verifies that comments are only posted on "commentable" lines (added or context lines in the diff) before calling the client.
Sources: packages/github/src/review-client.ts:114-160, README.md:144-150
Integration Summary
The GitHub API Integration Client acts as the gateway between the project and GitHub. It manages the lifecycle of a review from the initial pull_request webhook to the final createPRReview call. By isolating Octokit and JWT management within @repo/github, the rest of the application remains focused on AI orchestration and data ingestion.
Sources: packages/github/README.md, README.md:126-133