GitHub Projects GraphQL API adds multi-select field support
Introduced 2026-07-27 · score 0.98
HOW TO USE IT
When a Projects custom field needs multiple selections, create or update it with `dataType: MULTI_SELECT` and `multiSelectOptions`; to assign or read selections, use `multiSelectOptionIds` and query the item value’s `options` or `value`.
gh api graphql -f query='mutation { createProjectV2Field(input: { projectId: "<project-id>", name: "<field-name>", dataType: MULTI_SELECT, multiSelectOptions: [{ name: "<option-name>", description: "<description>", color: BLUE }] }) { projectV2Field { ... on ProjectV2MultiSelectField { id name multiSelectOptions { id name } } } } }'gh api graphql -f query='mutation { updateProjectV2Field(input: { fieldId: "<field-id>", multiSelectOptions: [{ id: "<existing-option-id>", name: "<option-name>", description: "<description>", color: BLUE }] }) { projectV2Field { ... on ProjectV2MultiSelectField { id name multiSelectOptions { id name } } } } }'gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "<project-id>", itemId: "<item-id>", fieldId: "<field-id>", value: { multiSelectOptionIds: ["<option-id>"] } }) { projectV2Item { fieldValues(first: 20) { nodes { ... on ProjectV2ItemFieldMultiSelectValue { value options { id name } } } } } } }'WHY THIS HELPS
Create or update a GitHub Projects custom field that stores multiple selected options, or read its selected values.
REQUIREMENTS AND LIMITATIONS
- CreateProjectV2FieldInput.projectId (required): Project node ID in which to create the field.
- CreateProjectV2FieldInput.name (required): Field name.
- CreateProjectV2FieldInput.dataType (required): Field type; use `MULTI_SELECT`. At least one `multiSelectOptions` value is required for this type.
- CreateProjectV2FieldInput.multiSelectOptions: Option list; at least one value is required when `dataType` is `MULTI_SELECT`. Each option has `name` (required), `description` (required), `color` (required; enum), and `id` (optional; preserves an existing option’s identity during updates). Docs do not state these keys are mutually exclusive.
- UpdateProjectV2FieldInput.fieldId (required): ID of the field to update.
- UpdateProjectV2FieldInput.multiSelectOptions: Options for a MULTI_SELECT field. Empty input is ignored; supplied values overwrite existing options, so fetch and include existing options for partial updates. Each option has `name`, `description`, and `color` required; `id` is optional and preserves existing option identity. Docs do not state these keys are mutually exclusive.
- ProjectV2MultiSelectField.multiSelectOptions(names:): Returns options; optional `names` filters by case-insensitive option names.
- UpdateProjectV2ItemFieldValueInput.projectId (required): Project node ID.
- UpdateProjectV2ItemFieldValueInput.itemId (required): ID of the item to update.
- UpdateProjectV2ItemFieldValueInput.fieldId (required): ID of the field to update.
- UpdateProjectV2ItemFieldValueInput.value (required): Field value input; only one value can be updated at a time.
- ProjectV2FieldValue.multiSelectOptionIds: IDs of the multi-select options to set.
- ProjectV2ItemFieldMultiSelectValue.options: Selected multi-select options.
- ProjectV2ItemFieldMultiSelectValue.value (required): Comma-separated names of selected options.
- Prerequisite: Authenticate GitHub CLI with `gh auth login --scopes "project"` for mutations; use `read:project` if only querying. The docs also allow a classic personal access token or GitHub App installation access token with the corresponding scope.
FIRST-PARTY EVIDENCE
- https://docs.github.com/en/graphql/overview/changelog#schema-changes-for-2026-07-27
- https://docs.github.com/en/graphql/reference/projects
- 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