GitHub Projects, Roadmaps, Custom Fields, Views, Automation, and Planning: Diagnostics, Failure Modes, Security, and Performance

1. The diagnostic sequence

1. Preserve evidence: Project number/URL, item URL/node ID, current fields, saved-view filter, issue/PR state, recent workflow event.
2. Identify scope: Project owner, repository owner, item type, field, view, workflow, credential/role.
3. Inspect independently: Project item list + source issue/PR + field definitions + permissions/API response.
4. Choose least destructive correction: fix one field/filter/permission/workflow rule before deleting or rebuilding anything.
5. Verify causality: repeat the same query and confirm both planning and source state.

2. Failure: labels, milestones, and Project fields disagree

Suppose an issue has label priority:p1, Project Priority=P2, and a milestone named “Emergency”. The problem is not choosing the correct color; the model has no declared authority. Preserve all three values, determine which process owns priority, then remove or rename the redundant representation. If labels are consumed by repository automation, perhaps keep a severity label and let the Project own business Priority instead of mirroring the same meaning.

gh issue view ISSUE --repo OWNER/REPO   --json number,title,state,labels,milestone,url

gh project item-list PROJECT --owner OWNER --limit 100   --field Status --field Priority --field Iteration --format json

3. Failure: the view looks healthy because it hides blocked or unassigned work

A saved view can filter aggressively. A board such as status:"In Progress" assignee:@me may be perfect for one engineer but dangerous as the executive backlog view. Diagnose the view definition, then query the underlying Project without the filter and create explicit risk views such as no:assignee, no:iteration, or high-priority work not Done.

# Underlying item inventory, not a saved UI view.
gh project item-list PROJECT --owner OWNER --limit 100   --field Status --field Priority --field Iteration --format json

# Current CLI supports advanced --query on github.com and GHES 3.20+.
gh project item-list PROJECT --owner OWNER --limit 100   --query 'no:assignee -status:Done'   --field Status --field Priority --format json

If your API host does not support --query, use the UI filter or inspect JSON locally. Do not silently treat an unsupported client/server feature as an empty result.

4. Failure: automation moves the field and nobody knows why

An issue is closed and the Project item becomes Done. That may be correct built-in behavior, not a human edit. Preserve the source issue timeline/state, Project workflow configuration, and the before/after field value. If the transition is undesirable, disable or narrow the workflow; do not immediately move every card back because that erases the symptom before the policy is understood.

More dangerous is a two-way policy where moving Status to Done closes the issue and closing the issue sets Status Done. It may stabilize rather than literally loop forever, but it creates ambiguous causality and can surprise maintainers. Prefer one authoritative direction.

5. Failure: “I can see the Project but cannot edit it”

Project access has Read, Write, and Admin roles. Underlying repository permissions remain separate. A collaborator might have Project Write but lack access to a private repository item, or have repository Write but only Project Read. For organization Projects, base roles and team grants add another layer. Diagnose both resources instead of asking for repository Admin as a blanket fix.

6. Intentionally broken example: missing Project authorization

# Suppose this fails with an authorization/permission error:
gh project item-list 7 --owner example-user --format json

echo "exit=$?"
gh auth status --active --hostname github.com

Interpretation: a valid GitHub login is not proof of Project API permission. Confirm the Project exists and is visible in the web UI, confirm the active account, then inspect whether the credential has the needed Project scope and whether you have Project access. Do not paste a token into the shell or grant broader repository/organization Admin rights to solve an API-scope problem.

7. Failure: Project says Done, PR is open, deployment never happened

This is the most important semantic failure in the chapter. Project Status is a planning field. If it says Done while the pull request is still open, either the field is stale or the team’s definition of Done means something other than merged. If the PR is merged but production is not deployed, Project Done still cannot prove deployment. Query each authoritative system independently.

gh pr view PR --repo OWNER/REPO   --json number,state,mergedAt,mergeCommit,statusCheckRollup,url

gh project item-list PROJECT --owner OWNER --limit 100   --field Status --field Priority --format json

If deployment proof is required, inspect the relevant GitHub deployment/environment or external CD system. Do not add a green “Deployed” Project field merely to avoid querying the real deployment evidence.

8. Destructive operations in this chapter

9. Scale, rate limits, and query correctness where they matter

gh project item-list defaults to a limited number of items, so production scripts should set an explicit limit or use documented pagination/API behavior. REST list endpoints are paginated. GraphQL requires cursor pagination. Large Projects also become hard to operate when every field is visible in every view; performance and cognition improve when saved views expose only the fields needed for the question.

Do not benchmark Projects by UI paint time alone and then delete metadata. First measure item count, field count, view/filter complexity, API pagination, and client/server version support.

10. Repair pattern: write the data contract before adding more automation

• Status: planning flow; updated automatically from close/merge where appropriate.
• Priority: Project-owned business ordering; not duplicated in labels.
• Iteration: planning commitment window; human-owned at planning time.
• Labels: repository classification and automation signals.
• Milestone: repository release/grouping when needed.
• Merged/deployed: read from PR/deployment systems, never inferred from Project Status alone.

11. Lesson summary

Project failures are usually model failures before they are UI failures. Preserve the Project field/view/workflow evidence, compare it with source-resource state and permissions, then make the smallest correction that restores an explicit authority boundary.

Knowledge check

Authoritative references

• Filtering projects
• Built-in Project automations
• Managing access to Projects
• Using the API to manage Projects
• gh project item-list
• REST Project item endpoints
• REST API versions