Bulk Random Assign

Bulk Random Assign is a specialized feature within Refined GitHub Projects designed to automate and distribute issue assignments across multiple users. It provides project managers and teams with a way to quickly balance workloads or assign tasks randomly using specific distribution strategies, bypassing the manual one-by-one assignment process native to GitHub Projects V2.

Sources: README.md:92, src/components/bulk/bulk-random-assign-modal.tsx:1-20

Architecture and Data Flow

The Bulk Random Assign feature follows the project's standard asynchronous messaging architecture. The process begins in the UI (Content Script), where users select items and configure assignment parameters in a modal. These parameters are then sent to a background service worker which executes the actual GitHub GraphQL mutations.

Assignment Lifecycle

The following sequence diagram illustrates the flow from user selection to background execution:

The background handler ensures rate-limit safety by processing assignments sequentially with a 1-second delay between mutations.

Sources: src/entries/background/handlers/bulk-handlers.ts:604-640, src/components/bulk/bulk-actions-bar.tsx:437-458

Distribution Strategies

The system implements three primary logic patterns for distributing items among selected assignees. These are encapsulated in the DistributionStrategy type and handled by the computeAssignments utility.

Sources: src/components/bulk/bulk-random-assign-utils.ts:1-15, src/lib/messages.ts:251

Balanced Distribution Logic

The balanced strategy is designed to prevent "assignment clusters" and ensures a fair spread of work.

Component Overview

UI Components

• BulkActionsBar: Triggers the handleRandomAssign function which validates the user's PAT before opening the configuration modal.
• BulkRandomAssignModal: A multi-step UI allowing users to select individuals from the repository's assignee pool and choose a distribution strategy. It provides a "Live Preview" of how items will be assigned before execution.

Sources: src/components/bulk/bulk-actions-bar.tsx:428-435, src/components/bulk/bulk-random-assign-modal.tsx:50-100

Data Structures

The assignment data is communicated between the frontend and backend using the BulkRandomAssignData interface:

export interface BulkRandomAssignData {
  itemIds: string[]
  projectId: string
  assignments: Array<{ itemId: string; assigneeIds: string[] }>
  strategy: 'balanced' | 'random' | 'round-robin'
}

Sources: src/lib/messages.ts:246-251

Background Processing and Safety

The assignment process is executed by the bulkRandomAssign handler in the background service worker. This handler is critical for maintaining GitHub's API integrity.

1. Concurrency Control: Checks isBulkFull() to prevent overwhelming the background queue.
2. ID Resolution: Converts DOM-based item IDs into real ProjectV2Item and Issue Node IDs using resolveProjectItemIds.
3. Atomic Updates: For each item, the handler first fetches current assignees via GET_ISSUE_ASSIGNEES, removes them via REMOVE_ASSIGNEES, and then adds the new ones via ADD_ASSIGNEES.
4. Rate Limiting: Strictly enforces a 1000ms sleep between mutations to avoid 403 Abuse alerts.

Sources: src/entries/background/handlers/bulk-handlers.ts:579-610, src/entries/background/handlers/bulk-handlers.ts:635-645

Summary

Bulk Random Assign provides a structured way to handle task distribution within GitHub Projects V2. By combining a flexible UI for user selection with rigid background queueing and multiple distribution strategies (Balanced, Random, Round-Robin), the system ensures that large-scale reassignments are both fair and compliant with GitHub API rate limits.