issue-fields-migration

What this skill does

# 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:

```bash
gh label list -R {owner}/{repo} --limit 1000 --json name,color,description
```

3. Fetch org issue fields:

```bash
gh api /orgs/{org}/issue-fields \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  --jq '.[] | {id, name, content_type, options: [.options[]?.name]}'
```

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:**

```
Labels in github/my-repo (showing relevant ones):
  p0, p1, p2, p3, bug, enhancement, frontend, backend

Org issue fields (single_select):
  Priority: Critical, P0, P1, P2, P3
  Type: Bug, Feature, Task
  Team: Frontend, Backend, Design

Suggested mappings:
  Label "p0" → Priority "P0"
  Label "p1" → Priority "P1"
  Label "p2" → Priority "P2"
  Label "p3" → Priority "P3"
  Label "bug" → Type "Bug"
  Label "frontend" → Team "Frontend"
  Label "backend" → Team "Backend"
  Label "enhancement" → (no auto-match; skip or map manually)

Confirm, adjust, or add more mappings?
```

#### 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:**

```
Potential conflict: labels "p0" and "p1" both map to the Priority field.
If an issue has both labels, which value should win?

Options:
  1. First match (use "p0" since it appears first in the mapping)
  2. Skip conflicting issues
  3. I'll decide case by case
```

#### Phase L3: Pre-flight Checks & Data Scan

1. For each repo, verify write access and cache the `repository_id`:

```bash
gh api /repos/{owner}/{repo} --jq '{full_name, id, permissions: .permissions}'
```

2. For each label in the mapping, fetch matching issues:

```bash
gh issue list -R {owner}/{repo} --label "{label_name}" --state all \
  --json number,title,labels,type --limit 1000
```

   **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 == "I