GitHub Integration & PRs

Relevant source files

The following files were used as context for generating this wiki page:

• lib/coding-agent/handleGitHubWebhook.ts
• lib/github/tests/createOrUpdateFileContent.test.ts
• lib/github/tests/getRepoFileTree.test.ts
• lib/github/tests/getRawFileContent.test.ts
• lib/coding-agent/tests/mergeGithubPR.test.ts
• lib/coding-agent/tests/mergeGithubBranch.test.ts
• lib/github/tests/getRepoGitModules.test.ts
• lib/github/tests/resolveSubmodulePath.test.ts
• CLAUDE.md

The GitHub integration system provides a robust interface for repository management, automated Pull Request (PR) updates, and file-level operations. It serves as the core infrastructure for the project's "Coding Agent," allowing it to interact with repositories, manage submodules, and respond to developer feedback through webhooks.

This system ensures that all code changes follow a strict workflow: changes are pushed to feature branches, PRs are opened against the test branch, and manual approval is required before merging.
Sources: CLAUDE.md:10-16, README.md:162-166

Repository Operations

The integration supports granular file and structure operations, including fetching raw content, updating files, and traversing repository trees.

File and Content Management

The system provides utilities to interact with specific files within a repository. This includes:

• Fetching Raw Content: Retrieving file data from raw.githubusercontent.com with support for both text and base64 encoding.
• Creating/Updating Files: Using the GitHub Content API to PUT file changes, which requires managing file SHAs for updates.
• Submodule Resolution: A specialized logic to detect if a path belongs to a submodule defined in .gitmodules and resolving the correct repository and relative path for that submodule.

Sources: lib/github/tests/getRawFileContent.test.ts:13-28, lib/github/tests/createOrUpdateFileContent.test.ts:43-55, lib/github/tests/resolveSubmodulePath.test.ts:13-26

Repository Tree Traversal

The system can fetch recursive file trees. It automatically expands submodule entries (type commit) into their respective directory structures by reading the .gitmodules file and fetching the sub-repo's tree.

The diagram above shows the process of fetching a repository tree and transparently expanding submodules.
Sources: lib/github/tests/getRepoFileTree.test.ts:19-35, lib/github/tests/getRepoFileTree.test.ts:98-125

Feature	Description	Relevant Files
Raw Content	Fetches file content with auth headers	getRawFileContent.ts
Tree Fetching	Recursive tree retrieval with submodule expansion	getRepoFileTree.ts
Submodule Mapping	Matches paths to submodule definitions	resolveSubmodulePath.ts
File Updates	Handles GitHub's requirements for SHAs when updating	createOrUpdateFileContent.ts

Coding Agent & Webhook Workflow

The system includes a dedicated webhook handler for processing GitHub events, specifically focusing on PR comments and reviews.

PR Feedback Loop

When a user mentions the bot (e.g., @recoup-coding-agent) in a PR comment or review, the handleGitHubWebhook function triggers an automated update process.

The sequence shows how incoming GitHub feedback is validated and transitioned into a background update task.
Sources: lib/coding-agent/handleGitHubWebhook.ts:20-45, lib/coding-agent/handleGitHubWebhook.ts:93-110

Git Workflow Rules

The project enforces a strict Git workflow that agents must follow:

1. Feature Branches: Never push to main or test directly.
2. Base Branch: Open PRs against the test branch.
3. Syncing: The test branch must be synced with main before starting new tasks.
4. No Auto-Merge: Agents must wait for explicit user approval before merging.

Sources: CLAUDE.md:10-23

Merging Strategies

The integration supports multiple merging methods used during different stages of the development lifecycle.

Squash Merging

Used primarily for PRs to maintain a clean history. The mergeGithubPR utility performs a PUT request to the GitHub pulls merge endpoint with the squash method.
Sources: lib/coding-agent/tests/mergeGithubPR.test.ts:13-24

Branch Merging

Used for syncing branches (e.g., merging main into test). This uses the GitHub merges API to perform a standard merge.
Sources: lib/coding-agent/tests/mergeGithubBranch.test.ts:13-28

Merging Utility	GitHub Endpoint	Logic/Method
mergeGithubPR	/pulls/{number}/merge	squash
mergeGithubBranch	/merges	Standard POST merge

Summary

The GitHub Integration & PR system provides a comprehensive bridge between the Recoup API and GitHub's infrastructure. By combining low-level file operations, submodule management, and an event-driven feedback loop, it enables the Coding Agent to operate autonomously within safe, human-reviewed boundaries. This architecture ensures code quality through mandatory feature branches and PR-based workflows while providing the flexibility to handle complex multi-repository (submodule) structures.
Sources: CLAUDE.md:10-16, lib/coding-agent/handleGitHubWebhook.ts:15-18