Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values

Issue Fields Migration [Issue fields](https://github.blog/changelog/2026 03 12 issue fields structured issue metadata is in public preview/) are org level typed metadata (single select, text, number, date) that replace label based workarounds with structured, searchable, cross repo fields. Every organization gets Priority , Effort , Start date , and Target date preconfigured, with support for up to 25 custom fields. This skill bulk migrates existing metadata into issue fields from two sources: Repo labels : Convert labels like p0 , p1 , priority/high into structured issue field values (e.g. the Priority field). Supports migrating multiple labels at once and optionally removing them after migration. Project V2 fields : Copy field values (single select, text, number, date, iteration) from a GitHub Project into the equivalent org level issue fields. When to Use User added org level issue fields that overlap with existing project fields User wants to copy values from project fields to issue fields before deleting the old project fields User asks about "migrating", "transferring", or "copying" project field data to issue fields User wants to convert repo labels (e.g., p0, p1, p2, p3) into issue field values (e.g., Priority field) User asks about replacing labels with issue fields or cleaning up labels after adopting issue fields Prerequisites The target org must have issue fields enabled The issue fields must already exist at the org level For project field migration: issue fields must be added to the project For label migration: labels must exist on the target repo(s) The user must have write access to the repos (and project, if migrating project fields) gh CLI must be authenticated with appropriate scopes Available Tools MCP Tools (read operations) Tool Purpose mcp github projects list List project fields ( list project fields ), list project items with values ( list project items ) mcp github projects get Get details of a specific project field or item CLI / REST API Operation Command List org issue fields gh api /orgs/{org}/issue fields H "X GitHub Api Version: 2026 03 10" Read issue field values gh api /repos/{owner}/{repo}/issues/{number}/issue field values H "X GitHub Api Version: 2026 03 10" Write issue field values gh api /repositories/{repo id}/issues/{number}/issue field values X POST H "X GitHub Api Version: 2026 03 10" input Get repository ID gh api /repos/{owner}/{repo} jq .id List repo labels gh label list R {owner}/{repo} limit 1000 json name,color,description List issues by label gh issue list R {owner}/{repo} label "{name}" state all json number,title,labels limit 1000 Remove label from issue gh api /repos/{owner}/{repo}/issues/{number}/labels/{label name} X DELETE See [references/issue fields api.md](references/issue fields api.md), [references/projects api.md](references/projects api.md), and [references/labels api.md](references/labels api.md) for full API details. Workflow Step 0: Migration Source Ask the user what they are migrating: 1. "Are you migrating labels or project fields?" Labels : proceed to the [Label Migration Flow]( label migration flow) below. Project fields : proceed to the [Project Field Migration Flow]( project field migration flow) below. 2. If the user says labels : Ask: "Which org and repo(s) contain the labels?" Ask: "Which labels do you want to migrate?" (they can name them or say "show me the labels first") 3. If the user says project fields : Ask: "Can you share the link to your project or tell me the org name and project number?" Ask: "Which field do you want to migrate?" Label Migration Flow Use this flow when the user wants to convert repo labels into issue field values. Labels can only map to single select issue fields (each label name maps to one option value). Phase L1: Input & Label Discovery 1. Ask the user for: org name and repo(s) to migrate. 2. Fetch labels from each repo: 3. Fetch org issue fields: 4. Filtering (for repos with many labels): if the repo has 50+ labels, group by common prefix (e.g., priority , team , type ) or color. Let the user filter with "show labels matching priority" or "show blue labels" before mapping. Never dump 100+ labels at once. 5. Ask the user which labels map to which issue field and option. Support these patterns: Single label to single field : e.g., label "bug" → Type field, "Bug" option Multiple labels to one field (bulk): e.g., labels p0, p1, p2, p3 → Priority field with matching options Multiple labels to multiple fields : e.g., p1 → Priority + frontend → Team. Handle as separate mapping groups. 6. Auto suggest mappings : for each label, attempt to match issue field options using these patterns (in order): Exact match (case insensitive): label Bug → option Bug Prefix number ( {prefix} {n} → {P}{n} ): label priority 1 → option P1 Strip separators (hyphens, underscores, spaces): label good first issue → option Good First Issue Substring containment : label type: bug → option Bug Present all suggestions at once for the user to confirm, correct, or skip. Example output: Phase L2: Conflict Detection After finalizing the label to option mappings, check for conflicts. A conflict occurs when an issue has multiple labels that map to the same issue field (since single select fields can hold only one value). 1. Group label mappings by target issue field. 2. For each field with multiple label sources, note the potential for conflicts. 3. Ask the user for a conflict resolution strategy: First match : use the first matching label found (by order of label mapping list) Skip : skip issues with conflicting labels and report them Manual : present each conflict for the user to decide Example: Phase L3: Pre flight Checks & Data Scan 1. For each repo, verify write access and cache the repository id : 2. For each label in the mapping, fetch matching issues: Warning : limit 1000 silently truncates results. If you expect a label may have more than 1000 issues, paginate manually or verify the total count first (e.g., gh issue list label "X" state all json number jq length ). PR filtering : gh issue list returns both issues and PRs. Include type in the json output and filter for type == "Issue" if the user only wants issues migrated. 3. If all selected labels return 0 issues , stop and tell the user. Suggest: try different labels, check spelling, or try a different repository. Do not proceed with an empty migration. 4. For multi repo migrations, repeat across all specified repos. 5. For each issue found: Check if the issue already has a value for the target issue field (skip if set). Detect multi label conflicts (issue has two labels for the same field). Apply the conflict resolution strategy chosen in Phase L2. Classify: migrate , skip (already set) , skip (conflict) , or skip (no matching label) . Phase L4: Preview / Dry Run Present a summary before any writes. Example preview: Phase L5: Execution 1. For each issue to migrate, write the issue field value (same endpoint as project field migration): Replace FIELD ID with the integer field ID (e.g., 1 ) and OPTION NAME with the option name string. 2. If the user opted to remove labels, remove each migrated label after successful field write: URL encode label names that contain spaces or special characters. 3. Pacing : 100ms delay between calls. Exponential backoff on HTTP 429 (1s, 2s, 4s, up to 30s). 4. Progress : report every 25 items (e.g., "Migrated 75/156 issues..."). 5. Error handling : log failures but continue. Include label removal failures separately. 6. Final summary : Project Field Migration Flow Use this flow when the user wants to copy values from a GitHub Project V2 field to the corresponding org level issue field. Follow these six phases in order. Always preview before executing. Phase P1: Input & Discovery 1. Ask the user for: org name and project number (or project URL). 2. Fetch project fields: 3. Fetch org issue fields: 4. Filter out proxy fields : after issue fields are enabled on a project, some project fields appear as "proxy" entries with empty options: [] for single select types. These mirror the real issue fields and should be ignored. Only match against project fields that have actual option values. 5. Auto match fields by name (case insensitive) with compatible types: Project Field Type Issue Field Type Compatible? TEXT text Yes, direct copy SINGLE SELECT single select Yes, option mapping needed NUMBER number Yes, direct copy DATE date Yes, direct copy ITERATION (none) No equivalent; skip with warning 6. Present the proposed field mappings as a table. Let the user confirm, adjust, or skip fields. Example output: Phase P2: Option Mapping (single select fields only) For each matched single select pair: 1. Compare option names between the project field and issue field (case insensitive). 2. Auto match options with identical names. 3. For any unmapped project field options, present all unmapped options in a single summary and ask the user to provide mappings for all of them at once. Do not prompt one by one; batch them into a single exchange. 4. Show the final option mapping table for confirmation. Example output: Phase P3: Pre flight Checks Before scanning items, verify write access to each repository that may be touched: 1. From the project items (first page), collect the unique set of {owner}/{repo} values. 2. For each unique repo, verify the authenticated user has Issues write permission: 3. If any repo shows push: false or triage: false , warn the user before proceeding. Items in those repos will fail at write time. 4. Cache the repository id (integer) for each repo now; you will need it in Phase 6: Phase P4: Data Scan 1. Fetch all project items using MCP. Important : for projects with more than ~200 items, gh api graphql paginate is unreliable (it concatenates JSON responses without proper separators and can time out). Use the MCP tool which handles pagination internally, or use explicit cursor based pagination: 2. For each item: Skip if it is a draft item (not a real issue). Extract the source project field value. Skip if the source value is empty. Check if the issue already has a value for the target issue field: If the issue field already has a value, skip it (preserve existing data). 3. Classify each item into one of: Migrate : has source value, no existing target value Skip (already set) : target issue field already has a value Skip (no source) : project field is empty for this item Skip (draft) : item is a draft, not a real issue Skip (unmapped option) : single select value was not mapped Phase P5: Preview / Dry Run Present a summary before any writes. If user requested dry run : show the full detailed report (every issue, its current value, proposed new value, and skip reason) and stop. Do not execute. Otherwise (preview mode) : show summary counts and a sample of changes, then ask for confirmation. Example preview: Phase P6: Execution 1. Use the repository id values cached in Phase 3. 2. For each item to migrate, write the issue field value: Replace FIELD ID with the integer field ID (e.g., 1 ) and VALUE with the value string. 3. Pacing : add a 100ms delay between API calls. On HTTP 429 responses, use exponential backoff (1s, 2s, 4s, up to 30s). 4. Progress : report status every 25 items (e.g., "Migrated 75/847 items..."). 5. Error handling : log f

issue-fields-migration