Bulk Close
Relevant source files
The following files were used as context for generating this wiki page:
The Bulk Close feature is a core component of the Refined GitHub Projects extension that allows users to mark multiple issues as "Completed" or "Not Planned" in a single operation. It addresses a limitation in the native GitHub Projects V2 interface where items often have to be closed individually.
This system operates through a decoupled architecture where a React-based UI component (Content Script) captures user intent and communicates with a Background Service Worker. The Background Service Worker manages a sequential task queue to execute GraphQL mutations, ensuring that the user's Personal Access Token (PAT) remains within rate limits and avoids concurrent request bans.
Sources: README.md:58-60, README.md:329-335, src/entries/background/handlers/bulk-handlers.ts:251-255
User Interface and Interaction
The entry point for the Bulk Close operation is the Bulk Actions Bar, which appears automatically when items are selected in the GitHub Projects table view.
Triggering the Operation
Users can trigger the process using the floating UI or a dedicated keyboard shortcut. Once the "Close Issues" action is selected, the system verifies the existence of a valid PAT before displaying the configuration modal.
| Interaction Method | Value / Key |
|---|---|
| Keyboard Shortcut | ⌘⇧X (Mac) / ⌃⇧X (Windows/Linux) |
| Menu Action | "Close Issues" under the "Status" group |
| Confirmation Modal | BulkCloseModal component |
Sources: src/components/bulk/bulk-actions-bar.tsx:645-661, src/components/bulk/bulk-actions-bar.tsx:1120-1148, src/components/bulk/bulk-close-modal.tsx:21-24
Close Reasons
The BulkCloseModal provides two specific state reasons for closing issues, mapped directly to GitHub's internal state logic:
- Completed: Indicates the issues are resolved.
- Not Planned: Indicates the issues will not be addressed.
Sources: src/components/bulk/bulk-close-modal.tsx:16-19, src/components/bulk/bulk-close-modal.tsx:63-108
System Architecture and Data Flow
The Bulk Close workflow follows a strict messaging pattern to maintain security and reliability.
The diagram shows the sequence from UI interaction to the sequential background execution. Sources: src/entries/background/handlers/bulk-handlers.ts:251-309, src/components/bulk/bulk-actions-bar.tsx:663-672
Background Execution Logic
The execution phase is handled in src/entries/background/handlers/bulk-handlers.ts. It follows a structured lifecycle to ensure data integrity and rate-limit safety.
1. Concurrency Control and Process ID
Before starting, the handler checks isBulkFull() to prevent exceeding the maximum number of concurrent bulk updates. It then generates a unique processId and acquires a lock via acquireBulk().
Sources: src/entries/background/handlers/bulk-handlers.ts:260-267
2. ID Resolution
Because the DOM only provides extracted database IDs (e.g., issue:12345), the background script must resolve these into real GitHub Global Node IDs (ProjectV2Item IDs) using the resolveProjectItemIds helper.
Sources: src/entries/background/handlers/bulk-handlers.ts:281, src/entries/background/helpers.ts:639-652
3. Sequential Queue Processing
The system builds a list of QueueTask objects. Each task executes the CLOSE_ISSUE GraphQL mutation. Crucially, the system implements a sleep(1000) (1 second) delay between every mutation to prevent the GitHub PAT from being flagged for abuse.
Sources: src/entries/background/handlers/bulk-handlers.ts:288-294, src/entries/background/handlers/bulk-handlers.ts:312, CONTRIBUTING.md:12-14
Data Structures
| Parameter | Type | Description |
|---|---|---|
itemIds | string[] | Array of IDs extracted from the DOM. |
projectId | string | The target ProjectV2 Node ID. |
reason | COMPLETED | NOT_PLANNED | The state reason for closing. |
issueNodeId | string | The resolved GraphQL Node ID of the issue. |
Sources: src/entries/background/handlers/bulk-handlers.ts:251-255, src/entries/background/handlers/bulk-handlers.ts:291
Progress Tracking
As the background queue processes items, it broadcasts updates back to the UI via broadcastQueue. This allows the "Live Queue Tracker" to display real-time percentage progress and human-readable status updates, such as "Closing item 2 of 10...".
Sources: src/entries/background/handlers/bulk-handlers.ts:297-313, README.md:200-203
Summary
The Bulk Close module ensures a safe and efficient way to manage issue statuses within GitHub Projects V2. By combining a Primer-styled React UI with a robust, sequential background worker, the system provides a native-feeling experience while strictly adhering to GitHub's API rate-limiting and concurrency guidelines.
Sources: README.md:73-75, src/entries/background/handlers/bulk-handlers.ts:316