Bulk Transfer
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Bulk Transfer is a core feature of the Refined GitHub Projects extension that allows users to move multiple issues from one repository to another while keeping their history intact. This operation is integrated into the GitHub Projects V2 table view, providing a streamlined workflow for migrating work across different project scopes without manual one-by-one transfers.
The system utilizes a client-side UI injected into the GitHub DOM that communicates with a background service worker to perform sequential, rate-limit-safe migrations using the GitHub GraphQL API. Sources: README.md:65, src/components/bulk/bulk-actions-bar.tsx:645-654
System Architecture
The Bulk Transfer system follows a decoupled architecture consisting of a React-based UI component for repository selection and a robust background handler for executing the transfer logic.
UI Component: BulkTransferModal
The BulkTransferModal is responsible for user interaction. It allows users to search for and select a target repository using an autocomplete interface. It leverages the searchTransferTargets message to fetch eligible repositories where the user has appropriate permissions and where issues are enabled. Sources: src/components/bulk/bulk-transfer-modal.tsx:40-112, src/entries/background/handlers/field-handlers.ts:145-155
Execution Logic: Background Handlers
The background script manages the lifecycle of the transfer process, including ID resolution, rate limiting, and status broadcasting. Transfers are executed sequentially with a 1-second delay between each operation to ensure the user's Personal Access Token (PAT) remains safe from 403/429 "Abuse" rate limits. Sources: src/entries/background/handlers/bulk-handlers.ts:490-550, src/entries/background/helpers.ts:672-680
The following diagram illustrates the high-level data flow for a bulk transfer operation:
This diagram shows the transition from the UI request to the sequential execution in the background worker. Sources: src/entries/background/handlers/bulk-handlers.ts:494-555, README.md:280-295
Technical Implementation
Repository Resolution
Before any transfer occurs, the system must resolve the target repository's unique GraphQL ID. The getRepositoryId helper function performs this look-up using the owner and name provided by the UI. Sources: src/entries/background/helpers.ts:589-592
Sequential Task Processing
The bulkTransfer handler uses processQueue to manage the migration of issues. Each task in the queue calls the TRANSFER_ISSUE mutation. Sources: src/entries/background/handlers/bulk-handlers.ts:526-532
| Function/Variable | Description | File Path |
|---|---|---|
bulkTransfer | Main message handler for initiating the transfer process. | src/entries/background/handlers/bulk-handlers.ts:490 |
getRepositoryId | Retrieves the GraphQL Node ID for a target repository. | src/entries/background/helpers.ts:589 |
resolveProjectItemIds | Maps DOM-extracted IDs to real ProjectV2Item Node IDs. | src/entries/background/helpers.ts:505 |
TRANSFER_ISSUE | GraphQL mutation used to move the issue. | src/entries/background/handlers/bulk-handlers.ts:16 |
Data Flow Sequence
The sequence of events from user confirmation to completion involves multiple asynchronous calls and progress updates.
This sequence details the interaction between the background worker and GitHub's API during a multi-item transfer. Sources: src/entries/background/handlers/bulk-handlers.ts:490-558
Rate Limit Handling
The system is designed to handle GitHub's primary and secondary rate limits gracefully. The withRateLimitRetry wrapper monitors for 403 or 429 status codes. If triggered, it broadcasts a "paused" state to the UI, extracts the Retry-After header, and waits for the specified duration before resuming. Sources: src/entries/background/helpers.ts:672-690
Conclusion
Bulk Transfer provides a critical utility for GitHub Projects V2 users, overcoming the platform's native limitation of one-by-one issue transfers. By utilizing a background queue and sequential execution, it ensures that even large-scale migrations are handled reliably and safely within GitHub's API constraints. Sources: README.md:38, src/entries/background/handlers/bulk-handlers.ts:548