github / github/awesome-copilot

skills/github-issues: Projects V2 reference gaps — project/field creation, singleSelectOptions overwrite semantics, view-creation limits

Closed Beginner friendly
#2,684 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
39k
Forks
5k
Avg merge
1d 22h
Merged PRs (30d)
113

Description

### Context

The `github-issues` skill's [`references/projects.md`](https://github.com/github/awesome-copilot/blob/main/skills/github-issues/references/projects.md) is an excellent reference for **item-level** Projects V2 operations. While setting up an org board today (2026-08-16) I hit four gaps, all verified against the live GraphQL schema via introspection before filing.

### Gap 1 — Creation-side admin is absent

The reference covers working within an existing project but never how to create the project or its fields:

```graphql
mutation($o:ID!,$t:String!){
createProjectV2(input:{ownerId:$o, title:$t}){ projectV2 { id number url } } # note: payload key is projectV2, not project
}
mutation($p:ID!){
createProjectV2Field(input:{projectId:$p, name:"Release", dataType:SINGLE_SELECT}){ projectV2Field{ id } }
}
```

The `projectV2` vs `project` payload-key distinction is exactly the kind of silent validation error agents hit (I did).

### Gap 2 — `singleSelectOptions` overwrite semantics undocumented

From schema introspection on `UpdateProjectV2FieldInput.singleSelectOptions`: *"Empty input is ignored, provided values overwrite existing options, and existing options should be fetched for partial updates."*

An agent that calls `updateProjectV2Field` with one option to "add" it will silently **replace the entire option list**. This is a data-loss footgun for board seeding.

### Gap 3 — `createProjectV2View` limits

`createProjectV2View` accepts only `name` + `layout` (`BOARD_LAYOUT` / `TABLE_LAYOUT` / `ROADMAP_LAYOUT`). Grouping (`groupByFields`), sort, filters, and date-axis are read-only via API (also raised in community discussion 153532). Without a warning, agents ship views that look empty/broken until a human opens the UI and applies grouping+filter manually — worth a callout in the reference.

### Gap 4 (minor) — `addProjectV2ItemById` idempotency

The docs mention it, the reference doesn't: re-adding existing content returns the existing item ID (no duplicate). One sentence so seed scripts can be safely re-run.

### Proposal

An "Advanced administration" (project/field creation + seeding) section in `references/projects.md` covering the above. Happy to open the PR if the approach sounds right.

Contributor guide

Open the contributing guide

Research direction

Start with skills/github-issues/references/projects.md and compare its item-level Projects V2 guidance with the four gaps described in the issue. Add an Advanced administration section covering project and field creation, singleSelectOptions overwrite semantics, view-creation limits, and addProjectV2ItemById idempotency. Done means the reference documents these behaviors accurately, including the projectV2 payload key and supported view layouts.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, graphql
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
84/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.