PaperClipAI/doc/project-repositories.md

Project source repositories

The Create project dialog accepts a name and optional GitHub repository selections. It uses the same RepositoryEditor as project Configuration. Description remains editable in Configuration. Status, goal links, and target dates remain supported by the API but are omitted from creation; Status and Goals are omitted from Configuration. Old Overview URLs and saved Overview preferences redirect to Configuration.

API and persistence

• GET /api/companies/:companyId/project-repositories returns repositories, connectionCount, and failedConnectionCount. Repository IDs are GitHub's stable numeric IDs represented as strings. Results are deduplicated across accessible grants and sorted by full name. Connection labels are display provenance only.
• POST /api/companies/:companyId/projects accepts optional repositoryIds. The server resolves new selections through the caller's authorized GitHub grants before creating the project and all repository workspaces in a transaction. The existing workspace input remains supported; it cannot be combined with repositoryIds.
• PUT /api/projects/:id/repositories accepts the selected repositoryIds array. Accessible retained IDs refresh their canonical name and URL after renames or transfers; unavailable retained IDs keep their saved metadata. Replacement is transactional. Existing selections may be retained or removed even if their GitHub connection becomes unavailable. New identities require current access. Legacy URL workspaces are preserved, and matching legacy URLs are adopted without creating a duplicate workspace. Local/remote workspace locations survive detaching their repository.

No schema migration is required. Selected repositories are normal project workspaces with metadata.githubRepositoryId. Existing manual repoUrl workspaces remain editable through Configuration and the workspace API. One workspace remains primary. Tasks materialize the other distinct repositories as editable checkouts inside their workspace, including when no local folders are configured. Local execution and sandbox staging use the same layout; sandbox restore preserves each repository's Git history. See Project Repository Checkouts for paths, ignore rules, and reuse behavior. Responsible-user credential rules still apply. A repository selection never delegates credentials.

Fresh tasks using the default repository workspace can clone the same authorized remote into a company- and task-scoped source directory when an existing project checkout contains another task's restricted workspace. The clone uses the run's Git connection and keeps separate Git metadata. Source access checks still apply before the task workspace is published. Low-trust review runs cannot use this persistent clone fallback. This fallback does not copy unpublished local changes or replace reused workspaces, explicit workspace selections, pinned branches, or repositories that only exist on the local filesystem. Configured branch templates must derive the branch from the task identifier, ID, title, or slug. Literal or task-independent templates retain the source denial, so a fresh clone cannot replace a selected local branch with a new empty branch. New implicit Git workspace defaults record their project-source provenance. An untyped checkout binding from an older task is ambiguous and keeps the denial, including explicit checkout IDs and inherited parent sources. Admission rechecks the current binding rather than inferring a default from the selected checkout ID. When the denial is retained, the run stops before the agent starts with a configuration_incomplete failure (reason workspace_source_restricted). The task is blocked with a notice that tells the owner to push unpublished work and select a new workspace, or to grant access to the restricted task, then retry. Paperclip does not report this owner action to Sentry as an unexpected run failure. This applies to both isolated-source checks and repository admission for a shared project workspace. Neither path replaces the existing workspace or retries the same access denial automatically. Startup validation of these recorded defaults keeps the task's effective workspace strategy. It does not substitute the agent's shared strategy or grant project writes. Workspace close and reopen use the recorded isolated source. Both operations verify its company, task, repository URL, and separate Git storage before use.

Discovery and setup

The server checks company membership, grant ownership/status, and organization-grant audiences before loading provider metadata. Connection managers receive no bypass to another person's personal repositories. Managed GitHub grants refresh installation access; PAT connections use paginated /user/repos. Provider failures are reported without exposing provider error bodies or credential material. Successful connections remain selectable when another connection fails.

ConnectionSetupFlow owns provider setup in both Apps and project dialogs. Task intents retain their existing callback protocol. Standalone dialogs verify the saved connection through the API after the sign-in popup returns to the instance. Project name and repository drafts stay mounted across setup and cancellation.

UI review and verification

Proposals/Project repos contains the reviewed states, including loading, failure, empty search, disconnected GitHub, multiple repos, legacy URLs, forty selections, mobile, and short viewports. The configuration story composes the production page properties through an explicit repositories slot. Story setup and saves use fixtures.

• Shared visual control: ui/src/components/RepositoryEditor.tsx.
• Data and error handling: ProjectRepositoryInput.tsx.
• Configuration persistence and legacy editing: ProjectRepositories.tsx and LegacyProjectRepository.tsx.
• Production dialog: NewProjectDialog.tsx.
• Server tests: project-repositories.test.ts and project-repositories-persistence.test.ts.
• Browser acceptance: tests/e2e/project-repositories.spec.ts.

The browser suite uses a real temporary server and database. It verifies creation, forty persisted repos, mobile scrolling, removal/save/reload, legacy URL editing, and rejection without a partial project. Provider discovery is simulated in the picker rejection test. GitHub network and popup behavior use deterministic fixtures in integration/component tests; the suite does not authorize a real GitHub account.