Issue Fields Migration
Migrate or script GitHub org issue custom fields using the Issue Fields REST API and gh with the required API version header.
Overview
Issue Fields Migration is an agent skill for the Build phase that documents GitHub Issue Fields REST endpoints and gh examples for listing, reading, and writing org custom issue metadata.
Install
npx skills add https://github.com/github/awesome-copilot --skill issue-fields-migrationWhat is this skill?
- Requires X-GitHub-Api-Version: 2026-03-10 on all Issue Fields calls
- List org issue fields via gh api /orgs/{org}/issue-fields
- Field types: text, single_select, number, date with jq filter examples
- Read per-issue values before write to avoid duplicate updates
- POST additive writes use repository_id integer—not owner/repo slug
- 4 documented field content types: text, single_select, number, date
- API version header: 2026-03-10
Adoption & trust: 1.6k installs on skills.sh; 34.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to move issues onto org issue fields but the versioned REST shape, jq filters, and repository_id write rules are easy to get wrong.
Who is it for?
Indie devs or small teams automating GitHub triage after enabling org issue fields on existing repositories.
Skip if: Projects still on classic labels-only workflows with no org issue fields enabled or no gh CLI access.
When should I use this skill?
You are migrating or scripting GitHub org issue custom fields and need the versioned REST endpoints and gh patterns.
What do I get? / Deliverables
You can run repeatable gh api commands to list fields, read values, and additively update issue field data during a migration.
- Copy-ready gh api commands for list, read, and additive write
- Migration checklist respecting repository_id and idempotent reads
Recommended Skills
Journey fit
Issue-field automation belongs in Build when you integrate GitHub org metadata into agents, bots, or repo workflows. Integrations fits REST/gh scripting against GitHub’s org-level issue fields—not local git history or PR review alone.
How it compares
Focused GitHub Issue Fields API cookbook—not a general issue templates or Projects v2 board skill.
Common Questions / FAQ
Who is issue-fields-migration for?
Builders and maintainers who script GitHub with gh and must migrate or sync org-level custom issue fields.
When should I use issue-fields-migration?
During Build integrations work when you bulk-read or write issue field values, validate API version headers, or plan additive POST migrations.
Is issue-fields-migration safe to install?
Treat it as operational API guidance; review Security Audits on this page and scope gh tokens minimally because writes change live issue metadata.
SKILL.md
READMESKILL.md - Issue Fields Migration
# Issue Fields REST API Reference Issue fields are org-level custom metadata for issues. All endpoints require the API version header: ``` -H "X-GitHub-Api-Version: 2026-03-10" ``` ## List Org Issue Fields ```bash gh api /orgs/{org}/issue-fields \ -H "X-GitHub-Api-Version: 2026-03-10" ``` Returns an array of field objects: ```json [ { "id": "IF_abc123", "name": "Priority", "content_type": "single_select", "options": [ { "id": "OPT_1", "name": "Critical" }, { "id": "OPT_2", "name": "High" }, { "id": "OPT_3", "name": "Medium" }, { "id": "OPT_4", "name": "Low" } ] }, { "id": "IF_def456", "name": "Due Date", "content_type": "date", "options": null } ] ``` **Field types**: `text`, `single_select`, `number`, `date` **Useful jq filter**: ```bash gh api /orgs/{org}/issue-fields \ -H "X-GitHub-Api-Version: 2026-03-10" \ --jq '.[] | {id, name, content_type, options: [.options[]?.name]}' ``` ## Read Issue Field Values ```bash gh api /repos/{owner}/{repo}/issues/{number}/issue-field-values \ -H "X-GitHub-Api-Version: 2026-03-10" ``` Returns the current field values for the issue. Use this to check whether a value already exists before writing. ## Write Issue Field Values (POST, additive) Adds values to an issue without removing existing values for other fields. **Important**: uses `repository_id` (integer), not `owner/repo`. ```bash # First, get the repository ID: REPO_ID=$(gh api /repos/{owner}/{repo} --jq .id) # Then write the value: echo '[ { "field_id": "IF_abc123", "value": "High" } ]' | gh api /repositories/$REPO_ID/issues/{number}/issue-field-values \ -X POST \ -H "X-GitHub-Api-Version: 2026-03-10" \ --input - ``` ### Value format by field type | Field Type | value format | Example | |-----------|-------------|---------| | text | String | `"value": "Some text"` | | single_select | Option name (string) | `"value": "High"` | | number | Number | `"value": 42` | | date | ISO 8601 date string | `"value": "2025-03-15"` | **Key**: for `single_select`, the REST API accepts the option **name** as a string. You do not need to look up option IDs. ### Writing multiple fields at once Pass multiple objects in the array to set several fields in a single call: ```bash echo '[ {"field_id": "IF_abc123", "value": "High"}, {"field_id": "IF_def456", "value": "2025-06-01"} ]' | gh api /repositories/$REPO_ID/issues/{number}/issue-field-values \ -X POST \ -H "X-GitHub-Api-Version: 2026-03-10" \ --input - ``` ## Write Issue Field Values (PUT, replace all) Replaces all field values on the issue. Use with caution. ```bash echo '[{"field_id": "IF_abc123", "value": "Low"}]' | \ gh api /repositories/$REPO_ID/issues/{number}/issue-field-values \ -X PUT \ -H "X-GitHub-Api-Version: 2026-03-10" \ --input - ``` **Warning**: PUT removes any field values not included in the request body. Always use POST for migrations to preserve other field values. ## Permissions - **Repository**: "Issues" read/write - **Organization**: "Issue Fields" read/write ## Rate Limiting - Standard rate limits apply (5,000 requests/hour for authenticated users) - Secondary rate limits may trigger for rapid sequential writes - Recommended: 100ms delay between calls, exponential backoff on 429 # Labels API Reference Reference for GitHub Labels REST API endpoints used in the label migration flow. ## List Labels in a Repository ``` GET /repos/{owner}/{repo}/labels ``` Returns all labels defined on a repository. Paginated (max 100 per page). **CLI shortcut:** ```bash gh label list -R {owner}/{repo} --limit 1000 --json name,color,description ``` **Response fields:** `id`, `node_id`, `url`, `name`, `description`, `color`, `default`. ## List Issues by Label ``` GET /repos/{owner}/{repo}/issues?labels={label_name}&state=all&per_page=100 ``` Returns issues (and pull requests) matching the label. Filter out PRs by checking `pull_request` field i