🔗 GitHub App Integration

gh.gg leverages GitHub App Integration to provide a powerful and secure experience, offering deeper insights into private repositories, higher API rate limits, and real-time automated features. This integration is crucial for transforming raw GitHub data into the intelligence layer that defines gh.gg.

🛡️ Authentication and Repository Access (src/lib/github/app.ts)

The src/lib/github/app.ts file is the core of gh.gg's GitHub App functionality. It manages the lifecycle of app authentication and provides utilities for interacting with the GitHub API on behalf of installations.

Key Concepts:

• GitHub App Initialization: The githubApp constant initializes the Octokit App, using GITHUB_APP_ID and GITHUB_PRIVATE_KEY environment variables. The isGitHubAppConfigured function checks if the necessary credentials are in place.
• JWT (JSON Web Token) Generation: generateAppJWT creates a time-limited token used to authenticate the app itself, necessary for actions like listing installations.
• Installation Token: When a user or organization installs the GitHub App, GitHub creates an installationId. getInstallationToken(installationId) uses the app's JWT to request an installation-specific access token. This token grants temporary permissions to interact with repositories under that specific installation.
• Installation Octokit: getInstallationOctokit(installationId) provides an authenticated Octokit instance using the installation token, allowing gh.gg to make API calls (e.g., fetch repository files, post comments) within the scope of that installation's permissions.
• Finding Installations:
  • getInstallationIdForRepo(owner, repo) determines if the app is installed on a specific repository.
  • getInstallationIdForAccount(accountId) finds the installation associated with a user or organization's GitHub account ID.
  • getUserFromInstallation(installationId) links a GitHub App installation back to a gh.gg user record in our database.
• Intelligent Repository Access: The getBestOctokitForRepo function is a crucial part of gh.gg's unified authentication strategy. It intelligently prioritizes access methods:
  1. It first checks if the currently logged-in gh.gg user has a linked GitHub App installation that covers the requested repository.
  2. If not, it attempts to find any GitHub App installation that covers the repository.
  3. As a fallback, it tries to use the user's OAuth token (if logged in).
  4. Finally, it falls back to a public app-level Octokit instance for public repositories, ensuring basic functionality even without specific user or repository installations.
• Permissions: The GitHub App requires specific permissions (e.g., Contents: Read-only, Pull requests: Read & write, Issues: Read & write) to perform its analysis and post comments. These are requested during the installation process.

🎣 Webhooks and Automated Features

GitHub Apps communicate real-time events (like code pushes or new pull requests) to gh.gg via webhooks. These webhooks trigger automated AI analysis processes. The src/db/schema.ts file defines webhookPreferences, which allows users to configure these automations. Functions like isPRReviewEnabled and isAnalysisEnabled (found in the comment service files) consult these preferences to determine if automation should run for a specific repository.

🤖 Automated PR Reviews (src/lib/github/pr-comment-service.ts)

This service is dedicated to providing AI-powered code reviews for pull requests.

• postPRReviewComment: This function is triggered by pull request webhook events.
  • It fetches all changed files in the PR, with pagination support and filtering for relevant code files (skipping binaries, lock files, generated code, etc., as defined in PR_REVIEW_CONFIG).
  • It then sends the PR title, description, and file patches to the Gemini AI via the analyzePullRequest module (src/lib/ai/pr-analysis.ts).
  • The AI generates a comprehensive analysis, including an overall score, breakdown of code quality, security, performance, and maintainability, along with actionable recommendations.
  • Finally, the service posts or updates a comment on the GitHub PR with the AI-generated markdown review. It uses a PR_REVIEW_CONFIG.commentMarker to identify and manage its own comments.
• isPRReviewEnabled: Checks if automated PR reviews are enabled for a given installation and repository, allowing users to opt-out or exclude specific repos.

🤖 Automated Issue and Commit Analysis (src/lib/github/commit-issue-comment-service.ts)

This service extends AI automation to individual commits and issues.

• postCommitAnalysisComment: Similar to PR reviews, this function analyzes a specific Git commit.
  • It fetches commit details and changed files.
  • It sends this data to the analyzeCommit module (src/lib/ai/commit-analysis.ts) for AI processing.
  • The AI provides a "slop ranking," commit message quality, code quality issues, and an AI generation likelihood score.
  • The service then posts or updates a comment on the commit with the detailed analysis, using a COMMIT_COMMENT_MARKER.
• postIssueAnalysisComment: This function analyzes GitHub issues for clarity, actionability, and completeness.
  • It retrieves issue details (title, body, labels, author).
  • This information is sent to the analyzeIssue module (src/lib/ai/issue-analysis.ts).
  • The AI generates insights including an overall score, "slop ranking," suggested labels, and priority.
  • The analysis is then posted or updated as a comment on the issue, identified by an ISSUE_COMMENT_MARKER.
• isAnalysisEnabled: Checks general automation preferences for commits and issues, similar to isPRReviewEnabled.

🛠️ GitHub App Setup

Integrating the GitHub App involves a few key steps:

1. Create a GitHub App: On GitHub, you register a new GitHub App in your developer settings. You'll specify details like the app name, homepage URL, and (crucially) the Webhook URL (e.g., https://github.gg/api/webhooks/github) and Webhook Secret.
2. Generate Private Key: GitHub provides a private key for your app. This key is vital for authenticating your app and generating installation tokens. It should be securely stored as an environment variable (GITHUB_PRIVATE_KEY).
3. Define Permissions & Events: During app creation, you configure the "Repository Permissions" (e.g., read contents, read/write pull requests/issues) and "Subscribe to Events" (e.g., push, pull_request, issue_comment). These dictate what your app can do and what events it receives.
4. Install the App: Users install your GitHub App on their personal or organization accounts, choosing which repositories to grant access to. This creates an installationId.
5. Link Installation to User: When a user signs into gh.gg via GitHub OAuth, gh.gg attempts to link their OAuth account to an existing GitHub App installation (if one exists), storing the installationId in the account table of the database (src/db/schema.ts). This allows gh.gg to use the more powerful GitHub App for that user's repositories.

Related Documentation:

• Getting Started: Provides initial setup instructions including GitHub OAuth.
• Core AI Analysis Modules: Details the AI modules that pr-comment-service.ts and commit-issue-comment-service.ts leverage for their analysis.

By combining the robust capabilities of GitHub Apps with advanced AI analysis, gh.gg delivers an intelligent and automated layer that enhances developer workflows and provides unprecedented insights into codebase health.