Issue Fields Migration

Issue fields 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)

CLI / REST API

See references/issue-fields-api.md, references/projects-api.md, and 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 below.
   • Project fields: proceed to the 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:

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

3. Fetch org issue fields:

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

…