Connecting a Codebase

Connecting a codebase to a project allows Software Factory to read and index the code via a Github App. This is enables several critical use cases, such as:

• Initializing your PRD from the codebase
• Reverse-engineering technical blueprints from existing code
• Identifying drift between the lateset code and the blueprints
• Writing implementation plans into work orders to guide coding agents

First, the Software Factory GitHub App must be enabled for your repository before connecting a codebase. The app provides secure, read-only access to the repository that you select. Open the Project Overview > Codebase tab. If the GitHub App is not yet installed, an Install GitHub App button will appear.

Select the GitHub organization or account where the app should be installed and choose which codebases it can access. After installation, GitHub returns you to Software Factory to complete setup.

In the Codebase tab, enter the HTTPS URL of the codebase you want to connect. Software Factory verifies that the GitHub App has access. Select the branch used for active development, then click Create Repository.

Software Factory reads files from the selected branch, chunks and embeds the code in the background, and displays progress as indexing completes.

Whenever code is pushed to the indexed branch, a webhook triggers reindexing to keep Software Factory up to date without manual action. Each reindexing job also reviews the latest code changes to detect drift with the project documentation in Software Factory. Project administrators can opt-in to automated reindexing.

A codebase connection can be removed at any time from the Codebase tab. Removing the connection deletes indexed content and removes the webhook but does not affect the GitHub App installation or the actual codebase. The connection can be re-added later.

• Connect the repository early so agents have code context from the start.
• Index the branch where active development occurs to keep documentation aligned. 
• After major refactors, check indexing status or manually reindex to ensure agents have updated context.