mirror of
https://github.com/github/awesome-copilot.git
synced 2026-03-13 20:55:13 +00:00
af09f9c38e
* Add issue-fields-migration skill Standalone skill to bulk-copy field values from Project V2 fields to org-level issue fields. Includes 5-phase workflow (discovery, option mapping, data scan, preview/dry-run, execution) with API references for issue fields REST API and Projects V2 API. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Expand issue-fields-migration skill to support label migration Add support for migrating repo-based labels to org-level issue fields, in addition to the existing project field migration flow. Changes: - Add Step 0 routing: ask user if migrating labels or project fields - Add Label Migration Flow (Phases L1-L5) with conflict detection, bulk mapping, and optional label removal - Add labels API to Available Tools table - Create references/labels-api.md - Add 3 label migration examples (single, bulk, cross-repo) - Expand Important Notes with label-specific guidance - Rename existing phases to P1-P6 under Project Field Migration Flow - Include P1 fixes from prior work (proxy field filtering, batch option mapping, preflight permission checks, pagination fixes) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: payload format, field_id type + 10 UX/scale improvements Bug fixes: - Wrap write endpoint payload in {"issue_field_values": [...]} (was bare array) - Use integer field_id, not string (both Phase L5 and P6) UX improvements: - Label filtering guidance for repos with 50+ labels - Smarter auto-suggest with 4 pattern tiers (exact, prefix-number, strip-separators, substring) - Handle zero-issue labels gracefully (stop and suggest alternatives) - Add time estimates to migration previews - Document read response shape (.single_select_option.name vs .value) Scale & reliability: - Script generation guidance for 100+ issue migrations - Idempotent/resumable migration note - Warn about --limit 1000 silent truncation - Warn about macOS bash 3.x (no declare -A) - PR filtering guidance (type field) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update README.skills.md with build Regenerated skills index to reflect label migration support and updated references for issue-fields-migration skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR review comments: fix MCP conventions, step numbering, pagination, phase refs - Align MCP tool calls with repo conventions (method: instead of action:, owner: instead of project_owner:) in SKILL.md and projects-api.md - Fix step numbering in Phase P2 (duplicate step 5 → renumber to 6) - Update example phase references to use P1-P6/P1-P5 labels - Add pageInfo pagination to GraphQL fields and fieldValues queries - Fix MCP tool name in labels-api.md to mcp__github__list_issues Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
3.3 KiB
3.3 KiB
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
gh api /orgs/{org}/issue-fields \
-H "X-GitHub-Api-Version: 2026-03-10"
Returns an array of field objects:
[
{
"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:
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
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.
# 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:
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.
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