Adding new options to ProjectV2 fields via the API clears existing issue assignments

[GuyvanderKolk]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

API

Body

What is the problem I am trying to solve?

As product owner, I interact with projects and issues on the daily. Recently, I tried to automate two things with Claude using GraphQL:

1. Some of our projects had the fieldname of Fix Version and the other had Fix Version/s. I was absolutely succesful in consolidating to one fixversion and was very excited about this, but in doing so I wiped out all the fixversions for all issues in my projects. Stupid on my part, and it reminded me how important it is to be careful.
2. Every week, we create new sprints across multiple projects which takes a fair amount of clicks. Being much more careful this time, I wanted to create a way to add the new sprints across all 30+ projects using updateProjectV2Field. Again, the result is that the moment the new iteration is created via the API, the sprint value assigned to existing issues is removed.

Do other people recognise this behaviour? Are Claude and I overlooking something obvious, or is that just a drawback of the API?

[Sahil-Mansuri-15]

This is a known and painful behavior of the ProjectV2 API you are not missing anything obvious.

When you call updateProjectV2Field to add a new option or iteration, GitHub replaces the entire field definition rather than appending to it. Any issue assignments referencing the old option IDs become orphaned because the IDs change with each update, effectively wiping all existing assignments.

The safe pattern is to always read the existing options first, then include all of them plus your new addition in the update call never send just the new item alone. Think of it as a full replace operation, not an append.

For sprint creation specifically across 30+ projects, the safer approach is using addProjectV2ItemById after creating the iteration rather than modifying the field definition directly. Create the iteration, grab its new ID from the response, then assign it to issues explicitly.

Before any field mutation touching production projects, pull the current field state with a query and store it. That gives you a restore point if something goes wrong which with this API behavior is genuinely easy to trigger.

Worth filing this at github.com/github/feedback as a bug or UX issue the API silently wiping assignments when a field is updated with no warning is not acceptable behavior for a production tool, and more reports increase the chance of GitHub adding proper append support or at least a warning.

If this helped, feel free to mark it as answered it helps others find the solution faster! 😊

[GuyvanderKolk]

Thank you for your gracious feedback! It is always good to know you are not crazy, and I was somewhat concerned I would be roasted for attempting this as a non-programmer.

[Luke-Corwin]

This sounds like expected behavior of the current GitHub Projects API rather than something Claude specifically did wrong.

When you update project field configurations—especially single-select and iteration fields—the API can replace parts of the field definition rather than simply append to it. If existing project items reference values that are modified, renamed, recreated, or assigned new IDs, those item values can be cleared.

I’ve seen similar reports with both single-select fields and iteration fields. The mutation succeeds, but existing assignments disappear because the underlying field options or iterations have effectively been replaced.

The safest approach is:

• Test all field mutations in a non-production project first.
• Avoid recreating field options or iterations if possible.
• Back up current field values before bulk changes.
• Use item-level updates for issue values and field-level updates only when absolutely necessary.
• Be especially cautious with iteration fields, as changing their configuration can affect every item currently assigned to an iteration.

Unfortunately, one of the drawbacks of automating Projects through GraphQL is that field configuration changes can have side effects that aren’t obvious from the mutation name alone. If you’re managing 30+ projects, I’d strongly recommend treating field updates as potentially destructive operations and validating them on a small test project before rolling them out broadly.

[GuyvanderKolk]

Yes, I have definitely seen that the first time I tried, and am therefore much more cautious. Thank you!

[Luke-Corwin]

Yes, I’ve seen similar behavior. updateProjectV2Field modifies the field definition, and for iteration/single-select fields that can unintentionally clear existing values if options or iterations are changed or recreated.

In practice, I treat field-level mutations as schema changes, not data changes. If possible, use item-level mutations for updating issue values and be very cautious when modifying iteration fields.

Unfortunately, this seems more like a limitation/sharp edge of the current API than something Claude overlooked.

[GuyvanderKolk]

Thank you!