Easy Bulk Import Issues

Bulk import GitHub issues to Linear with automated field mapping, label conversion, priority assignment, and progress tracking for large-scale project migrations.

When to Use This Command

Run this command when...

• You are migrating a project from GitHub Issues to Linear and need to transfer dozens or hundreds of issues with their metadata preserved
• You want automated mapping of GitHub labels to Linear labels, milestones to projects, and assignees to team members
• Your migration requires filtering, transformation, or enrichment of issues during the import process

Do NOT use this command when...

• You need to import a single issue -- use the issue-to-linear command for individual transfers
• You want bidirectional sync rather than a one-time import -- use the bidirectional invoker command

Quick Start

Copy
# .claude/commands/easy-bulk-import-issues.md
# Bulk import GitHub issues to Linear
Import: $ARGUMENTS

Copy
# Run the command
claude "easy-bulk-import-issues import all open bugs from github.com/org/repo to Linear Backend team"

Expected output:
- Issue inventory with count and metadata summary
- Field mapping configuration (labels, assignees, priorities)
- Import progress with success/skip/error counts
- Cross-reference links between GitHub and Linear items
- Migration summary report

Core Concepts

Concept	Description
Issue Inventory	Scanning and cataloging all GitHub issues matching the import criteria
Field Mapping	Converting GitHub fields (labels, milestones, assignees) to Linear equivalents
Batch Processing	Importing issues in batches with rate limiting and error handling
Cross-Referencing	Adding bidirectional links between original GitHub issues and new Linear tasks
Progress Tracking	Real-time reporting of import progress with error recovery

Bulk Import Pipeline:

  GitHub Repository
       |
  [Scan Issues (filter)]
       |
  [Inventory & Preview]
       |
  +----+----+----+
  |    |    |    |
 Map   Map   Map  Map
 Labels Assign Priority Status
  |    |    |    |
  [Batch Import to Linear]
       |
  [Add Cross-References]
       |
  Migration Report

Configuration

Parameter	Default	Description
Filter	All open issues	GitHub issue state and label filters for import selection
Batch Size	25	Number of issues processed per API batch
Label Mapping	Auto-match by name	How GitHub labels map to Linear labels
Assignee Mapping	By email	How GitHub usernames map to Linear team members
Dry Run	Preview first	Show what would be imported before executing

Best Practices

1. Preview before importing -- always run with dry-run mode first to verify the issue count, field mappings, and any items that will be skipped or need manual attention
2. Map labels in advance -- create matching labels in Linear before importing, or provide an explicit mapping. Auto-matching by name only works if label names are identical
3. Import in phases -- start with a small batch (10-20 issues) to validate the mapping, then import the remainder. This catches configuration errors early
4. Preserve GitHub references -- configure cross-referencing to add the GitHub issue URL in the Linear task description for traceability back to the original
5. Handle attachments separately -- GitHub issue attachments (images, files) may not transfer automatically. Review the migration report for items with attachments needing manual handling

Common Issues

1. Rate limiting errors -- GitHub and Linear APIs have rate limits. Reduce batch size and add delays between batches if you encounter 429 status codes
2. Missing assignees -- GitHub usernames that do not match any Linear team member will result in unassigned tasks. Provide an explicit user mapping for accuracy
3. Duplicate imports on re-run -- if the command is run twice, it may create duplicates. Use the cross-reference check to skip already-imported issues on subsequent runs