{
  "slug": "github-projects-graphql-api-adds-multi-select-field-support-18e250521e3e",
  "title": "GitHub Projects GraphQL API adds multi-select field support",
  "tools": [
    "github-graphql-api"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-07-27T00:00:00.000Z",
  "announced_at": "2026-07-27T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "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`.",
    "examples": [
      "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 } } } } } } }'"
    ],
    "gotchas": [
      "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."
    ]
  },
  "why_it_matters": "Create or update a GitHub Projects custom field that stores multiple selected options, or read its selected values.",
  "sources": [
    "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"
  ],
  "rank": 0.98043,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-tools-20261017",
    "verdict_id": "wave1b-tools-20261017:wave1b-tools-20261017-2e9117437c760044-0:gate",
    "evidence_hash": "aaf5f3062b5c51dd6ebebd121786a816d931e14b19fd8887a83e4a942d84bccf"
  },
  "review": {
    "draft_hash": "3a4190bb368f2e3d7c3b24accbf1eb035d08c0e304991f5ed76b05eca3553801",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-tools-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.98 >= 0.9; 2 needed) and Jev gave 0.80 (>= 0.6 needed)."
  }
}