Issue Fields Migration

Issue fields migration

Migrate existing GitHub issue metadata into organization-level issue fields by planning mappings, detecting conflicts, writing values idempotently through the REST API, and optionally removing label-based source labels only after explicit approval. This skill bulk-migrates both repo-scoped labels and cross-repo Project V2 metadata.

When to invoke

• "Migrate my labels to issue fields."
• "Copy Project V2 field values to issue fields."
• "Convert p0/p1 labels into the Priority field."
• "Adopt issue fields and clean up old labels."
• "Move project metadata before deleting project fields."

Prerequisites and context

• The target organization must have issue fields enabled.
• Issue fields must already exist at the organization level; every organization gets Priority, Effort, Start date, and Target date preconfigured, with up to 25 custom fields.
• For project field migration, issue fields must be added to the project.
• For label migration, source labels must exist on target repositories.
• The user needs write access to repositories and to the project when migrating project fields.
• gh CLI must be authenticated with scopes sufficient to read labels/projects and write issue field values.
• Use API header X-GitHub-Api-Version: 2026-03-10 for issue fields endpoints.

Migration sources

API and CLI commands

Use references/issue-fields-api.md, references/projects-api.md, references/labels-api.md, and references/migration-workflow.md for full command payloads and end-to-end examples.

Procedure

1. Identify organization, repositories, source labels or project, target issue fields, and desired label-removal policy.
2. List organization issue fields and confirm target field names and option names.
3. For label migration, list labels and issues; URL-encode label names with spaces or special characters such as good%20first%20issue in REST paths.
4. For project migration, list project items and field values; skip iteration fields and draft items with notes.
5. Cache each repository ID per-repo and per-repository with gh api /repos/{owner}/{repo} --jq .id; the write endpoint uses integer repository_id, not owner/repo.
6. Read existing issue field values and skip any issue where the target value is already set.
7. Detect label conflicts before execution when one issue has multiple labels mapping to the same single_select field.
8. For migrations of 100+ issues, generate a standalone POSIX-compatible shell script instead of executing one API call at a time through the agent.
9. Write field values idempotently with the REST API; use single-select option names as strings, not option IDs.
10. Read values back and use .single_select_option.name for human-readable verification; .value may be an internal option ID like 1201.
11. re-running the migration is safe because existing target values are skipped; remove labels only if the user explicitly approved removal after migration.

Gotchas

• Repository ID is required for writes: /repositories/{repo_id}/issues/{number}/issue-field-values does not accept owner/repo.
• Single-select writes use names: send option names as strings, not option IDs.
• Readback names are nested: use .single_select_option.name; .value may be an integer ID.
• gh issue list includes PRs: include type in --json and filter type == "Issue" when PRs are out of scope.
• --limit 1000 truncates silently: gh issue list --limit 1000 stops at 1000 results; paginate with --jq and cursor-based pagination or split by date range when labels exceed 1000 issues.
• macOS bash 3.x lacks declare -A: generated scripts should be POSIX-compatible or explicitly require newer bash via brew install bash.
• Label removal is optional: never remove source labels without approval.

Progressive disclosure and bundled resources

• references/migration-workflow.md: end-to-end workflow, payloads, dry-run structure, conflict handling, and execution examples.
• references/issue-fields-api.md: issue fields REST endpoints and value formats.
• references/projects-api.md: Project V2 field/item reads and mapping guidance.
• references/labels-api.md: label inventory, issue discovery, and label removal details.

Output template

## Issue fields migration result

**Status:** planned | migrated | blocked
**Organization:** `<org>`
**Source:** labels | Project V2
**Target field:** `<field name>`

### Mapping
| Source value | Target issue field | Target value | Issues matched | Conflicts |
| --- | --- | --- | --- | --- |
| `p0` | `Priority` | `High` | <count> | <count> |

### Execution
- Repository IDs cached: <count>
- Existing values skipped: <count>
- Values written: <count>
- Draft items skipped: <count>
- Iteration fields skipped: <count>
- Labels removed: <count or "not approved">

### Validation
- Readback command: `<command>`
- Sample verified issues: <numbers>
- Remaining risks: <pagination, permissions, conflicts, or "none">

Quality gate

• Target issue fields exist and option names are known.
• X-GitHub-Api-Version: 2026-03-10 is used on issue fields endpoints.
• Repository IDs are cached per repository before writes.
• Existing issue field values are preserved and skipped.
• Label conflicts, iteration fields, draft items, and PR filtering are handled explicitly.
• Migrations of 100+ issues use or produce a standalone resumable script.
• Label names in REST paths are URL-encoded.
• Source labels are removed only with explicit approval.
• Readback uses .single_select_option.name for human-readable values.

References

• Issue fields public preview changelog