Bulk Edit Wizard
Relevant source files
The following files were used as context for generating this wiki page:
The Bulk Edit Wizard is a central feature of the Refined GitHub Projects extension that allows users to update multiple fields and relationships across several GitHub Project items simultaneously. It solves the limitation of GitHub Projects V2 where items must typically be edited one at a time. The wizard operates entirely within the browser, utilizing the user's Personal Access Token (PAT) to interface directly with the GitHub GraphQL API.
The system is designed with a three-step guided flow: field selection, value assignment, and change review. This structure ensures that users can see a clear "diff" of their intended changes before any API mutations are executed. To maintain security and performance, all mutations are handled by a background service worker that processes tasks sequentially to avoid rate-limiting or PAT bans.
Sources: README.md:104-106, src/components/bulk/bulk-edit-modal.tsx:47, src/entries/background/handlers/bulk-handlers.ts:48-50
Architecture and Data Flow
The Bulk Edit Wizard follows a decoupled architecture between the UI (Content Script) and the execution logic (Background Service Worker). This separation ensures that complex API operations do not block the GitHub user interface and that security-sensitive tokens remain isolated.
High-Level Component Interaction
The data flow begins when the user selects items in the GitHub Project table view. The BulkActionsBar detects the selection and provides an entry point to the BulkEditWizard. Once the user confirms the changes, a message is sent via sendMessage to the background script, which orchestrates the sequential execution of mutations.
Sources: src/components/bulk/bulk-actions-bar.tsx:645-662, src/entries/background/handlers/bulk-handlers.ts:60-65, src/components/bulk/bulk-edit-modal.tsx:1152-1200
User Interface Steps
The wizard is implemented as a React-based modal that transitions through several distinct states defined by the WizardStep type.
Step 1: Field Selection
In the FieldsStep component, users choose which standard fields, custom project fields, or issue relationships they wish to modify. The system categorizes these into:
- Standard Fields: Title, Body, Comment, Assignees, Labels, and Issue Type.
- Custom Fields: Fields defined specifically for the project (Single Select, Iteration, Text, Number, Date).
- Relationships: Parent, Blocked By, and Blocking.
Sources: src/components/bulk/bulk-edit-modal.tsx:482-515, src/components/bulk/bulk-edit-modal.tsx:47
Step 2: Value Assignment
The ValuesStep dynamically renders input components based on the dataType of the selected fields.
- Single Select/Iteration: Renders selectable buttons or panels for specific options.
- Metadata (Assignees/Labels): Uses
RepoMetadataSelectPanelto fetch and select repository-level entities. - Relationships: Provides specialized editors for managing issue dependencies and hierarchy.
Sources: src/components/bulk/bulk-edit-modal.tsx:758-940
Step 3: Review and Apply
The SummaryStep provides a final summary of all configured changes. It also performs final validation, checking for concurrent process limits and relationship conflicts (e.g., an issue cannot be its own parent).
Sources: src/components/bulk/bulk-edit-modal.tsx:1037-1065, src/entries/background/helpers.ts:456-470
Technical Implementation Details
Data Structures
The following core interfaces define the state management within the wizard:
| Interface | Purpose | Key Fields |
|---|---|---|
ProjectField | Represents a project column | id, name, dataType, options, configuration |
BulkEditRelationshipsUpdate | Stores relationship changes | parent, blockedBy (add/remove/clear), blocking |
ResolvedItem | Links DOM IDs to GitHub Node IDs | domId, projectItemId, issueNodeId, repoOwner, repoName |
Sources: src/components/bulk/bulk-edit-modal.tsx:21-34, src/entries/background/helpers.ts:866-880
Background Execution Queue
To prevent GitHub from banning the user's PAT due to abusive concurrent mutations, the project implements a strict sequential queue.
Tasks are created for every individual field update on every item. For example, updating the "Status" and "Assignee" of 5 issues results in 10 sequential tasks in the queue.
Sources: src/entries/background/handlers/bulk-handlers.ts:98-150, src/entries/background/handlers/bulk-handlers.ts:255-275
Relationship Validation Logic
Before applying updates, the background script validates relationship integrity. The getBulkRelationshipValidationErrors function checks for several failure conditions:
- Self-Parenting: An issue cannot be assigned as its own parent.
- Circular Dependencies: An issue cannot both block and be blocked by the same issue.
- Self-Blocking: An issue cannot block itself.
Sources: src/entries/background/helpers.ts:444-515
Conclusion
The Bulk Edit Wizard provides a high-efficiency interface for GitHub Projects V2 by batching complex mutations and providing a safe, reviewed execution environment. By leveraging a sequential background queue and robust client-side validation, it ensures that project management operations are both powerful and safe from API rate-limit penalties.
Sources: README.md:121-125, src/entries/background/handlers/bulk-handlers.ts:285-290