github / github/awesome-copilot
skills/github-issues: Projects V2 reference gaps — project/field creation, singleSelectOptions overwrite semantics, view-creation limits
- 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
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