GitHub GraphQL adds project issue field value types
Introduced 2026-03-12 · score 0.93
HOW TO USE IT
When reading issue field values on project items, query `fieldValues` for `ProjectV2ItemIssueFieldValue` and select its `field` and `issueFieldValue`. Handle the returned union as date, number, single-select, or text values. ([Projects reference](https://docs.github.com/en/graphql/reference/projects), [Issues reference](https://docs.github.com/en/graphql/reference/issues))
gh api graphql -f query='
query {
node(id: "<PROJECT_ID>") {
... on ProjectV2 {
items(first: 20) {
nodes {
id
fieldValues(first: 20) {
nodes {
... on ProjectV2ItemIssueFieldValue {
field { ... on ProjectV2FieldCommon { name } }
issueFieldValue {
... on IssueFieldDateValue { value }
... on IssueFieldNumberValue { value }
... on IssueFieldSingleSelectValue { name }
... on IssueFieldTextValue { value }
}
}
}
}
}
}
}
}
}'WHY THIS HELPS
Read issue field values associated with project items through the GitHub GraphQL API.
REQUIREMENTS AND LIMITATIONS
- node(id:) (required): Pass the project node ID; the query narrows the node to `ProjectV2`.
- items(first:): Requests the first n project items.
- fieldValues(first:): Requests the first n field values for each project item.
- ProjectV2ItemIssueFieldValue.field: The project field containing this value; the query selects its name.
- ProjectV2ItemIssueFieldValue.issueFieldValue: The issue field value, returned as the `ProjectV2IssueFieldValues` union.
- IssueFieldDateValue: Union member for date field values; its `value` is a string.
- IssueFieldNumberValue: Union member for number field values; its `value` is a float.
- IssueFieldSingleSelectValue: Union member for single-select values; `name` is the option's name.
- IssueFieldTextValue: Union member for text field values; its `value` is a string.
- Prerequisite: Authenticate with a token that has the `read:project` scope to read projects; GitHub CLI authentication can use `gh auth login --scopes "read:project"`.
- Docs conflict: Current documentation includes later additions to `IssueFieldSingleSelectValue`: `optionId` on 2026-03-17 and `value` on 2026-03-31. The query uses `name`, which the current reference documents; these later fields postdate the card. https://docs.github.com/en/graphql/overview/changelog
FIRST-PARTY EVIDENCE
- https://docs.github.com/en/graphql/overview/changelog#schema-changes-for-2026-03-12
- https://docs.github.com/en/graphql/reference/projects
- https://docs.github.com/en/graphql/reference/issues
- https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects
Check the installed version and the source before using it. Entry JSON