Issue-Fields-Migration

# 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