Bulk Pin & Unpin

Introduction

The Bulk Pin & Unpin feature in Refined GitHub Projects allows users to promote or demote multiple issues at the repository level simultaneously from the GitHub Projects table view. This functionality addresses the limitation in GitHub Projects V2 where visibility status (pinning) must typically be managed individually.

By integrating with the sequential background queue, the system ensures that multiple pin/unpin operations are executed safely without triggering GitHub's secondary rate limits or abuse detection mechanisms. This feature is part of the project's "Visibility" action suite, accessible through the Bulk Actions Bar.

Sources: README.md:94, README.md:143, src/components/bulk/bulk-actions-bar.tsx:1037-1087

Architecture and Data Flow

The Bulk Pin and Unpin operations follow the project's standard modular background architecture. The process begins in the Content Script (UI layer) and is executed by the Background Service Worker.

UI Interaction

Users trigger the flow by selecting items in the project table and choosing "Pin Issues" or "Unpin Issues" from the action menu. The BulkActionsBar component handles the initial user intent and triggers a confirmation modal before sending a message to the background script.

Sources: src/components/bulk/bulk-actions-bar.tsx:758-778, src/components/bulk/bulk-actions-bar.tsx:1037-1087

Background Processing

The background handler registerBulkHandlers listens for bulkPin and bulkUnpin messages. It follows a multi-step execution logic:

1. Concurrency Check: Checks if the maximum number of concurrent bulk updates has been reached.
2. Item Resolution: Converts DOM-extracted database IDs into real ProjectV2Item Node IDs.
3. Task Creation: Generates a list of QueueTask objects, each containing a GraphQL mutation.
4. Sequential Execution: Processes tasks through the sequential queue with a mandatory 1-second delay between mutations.

Sources: src/entries/background/handlers/bulk-handlers.ts:474-539, src/entries/background/handlers/bulk-handlers.ts:543-605

Component Diagram

The following diagram illustrates the relationship between the UI components and the background handlers responsible for pinning operations.

The flow ensures that every mutation is isolated and delayed to protect the user's Personal Access Token (PAT).
Sources: src/entries/background/handlers/bulk-handlers.ts:489-530, CONTRIBUTING.md:13-17

Technical Implementation

GraphQL Mutations

The system utilizes two primary GraphQL mutations defined in the library to interact with GitHub's API.

Sources: src/lib/graphql/mutations.ts:162-174

Background Handlers

The handlers in bulk-handlers.ts manage the lifecycle of the operation, including broadcasting progress updates back to the UI.

// From src/entries/background/handlers/bulk-handlers.ts:505
const tasks: QueueTask[] = resolvedItems.map(({ domId, issueNodeId }) => ({
  id: `pin-${domId}`,
  run: async () => {
    await gql(PIN_ISSUE, { issueId: issueNodeId })
    await sleep(1000)
  },
}))

Sources: src/entries/background/handlers/bulk-handlers.ts:505-512, src/entries/background/handlers/bulk-handlers.ts:572-578

Sequence Diagram: Execution Flow

The sequence diagram below shows the interaction between the user, the extension layers, and GitHub's API during a bulk pinning operation.

Usage and Shortcuts

The feature is integrated into the BulkActionsBar and supports standard keyboard shortcuts for efficiency.

Sources: src/components/bulk/bulk-actions-bar.tsx:288-295, src/components/bulk/bulk-actions-bar.tsx:1037-1070, README.md:143

Constraints and Requirements

• Administrative Rights: Pinning issues typically requires specific repository permissions (admin or maintainer level).
• Sequential Rate Limiting: The system enforces a 1-second delay between each pin or unpin action to prevent 403 Abuse alerts.
• GitHub PAT: A Personal Access Token with the repo scope is required to perform these mutations.

Sources: README.md:146, README.md:270, CONTRIBUTING.md:13-17

Summary

Bulk Pin & Unpin provides an automated way to manage the visibility of multiple issues within a repository. By leveraging a sequential task queue and GraphQL mutations, the system ensures that these operations are performed reliably and safely, adhering to GitHub's API best practices while providing a seamless bulk-edit experience for the user.