GitHub Projects, Roadmaps, Custom Fields, Views, Automation, and Planning: Concepts, Architecture, and Mental Model

1. The problem: a clean issue queue is not yet a release plan

Chapter 05 gave incoming work consistent issue semantics. A release lead now needs different questions: Which items are being considered for the next iteration? Which high-priority work has no owner? Which pull requests are in review? Which work is expected this month? A repository issue list can answer parts of those questions, but it is intentionally repository-centric. A GitHub Project adds a planning layer that can gather issues, pull requests, and draft ideas into one model and attach planning-specific fields and views.

2. Mental model: one planning model, many source records

flowchart LR
  I[Repository Issue] --> PI[Project item]
  PR[Pull request] --> PI2[Project item]
  D[Draft item] --> PI3[Project item]
  PI --> F[Project fields: Status / Priority / Iteration]
  PI2 --> F
  PI3 --> F
  F --> V1[Table view]
  F --> V2[Board view]
  F --> V3[Roadmap view]
  I -. authoritative issue state .-> S1[open / closed / assignees / labels]
  PR -. authoritative PR state .-> S2[open / merged / checks / review]

The solid arrows show Project membership and Project-field data. The dashed arrows show a different authority boundary: issue and PR lifecycle data belongs to those hosted resources. The same Project item can be rendered in a table, board, or roadmap; changing the layout does not duplicate the item.

3. Items, drafts, and linked engineering work

A Project item is a row/card/timeline entry. For a linked issue or pull request, the item references that GitHub resource and surfaces selected metadata. A draft item is a Project-native idea that has not yet become an issue. Drafts are useful for tentative planning, but they have no repository issue number, no Git branch, and no pull-request checks. When work becomes actionable, teams often convert or replace the draft with a real issue so ownership and repository history become explicit.

4. Fields: separate reusable planning semantics from repository metadata

Projects expose built-in metadata from issues and pull requests and allow custom fields such as text, number, date, single-select, and iteration. A single-select Priority field can express P0/P1/P2 across multiple repositories. An Iteration field represents repeating time boxes and automatically creates several iteration windows when configured. Status is commonly a single-select planning field such as Todo, In Progress, and Done.

5. Table, board, and roadmap are questions, not competing sources of truth

A view stores a layout plus presentation choices such as visible fields, filters, grouping, and sorting. Table is best for dense inspection and bulk planning; board is best when a categorical field such as Status is the main question; roadmap is best when dates or iterations provide a time axis. Saving multiple views lets the same items answer different operational questions without copying them.

6. User Projects, organization Projects, and repository linkage

Projects can be owned by a user or an organization. A user-owned Project is appropriate for personal planning and can track issues and pull requests from repositories owned by that personal account. Organization Projects support team/base access models and shared governance. Linking a Project to a repository improves discoverability; it does not move ownership of the Project into the repository. GitHub only lists a linked Project in a repository when the Project and repository share the same user or organization owner.

Project visibility and repository visibility are independent. A public Project can contain an item from a private repository, but a viewer still needs repository permission to see that private item. GitHub may return or display redacted/hidden item information where the viewer lacks the underlying repository access.

7. Built-in workflows change planning state; some workflows can change source state

Projects includes built-in workflows. Current GitHub documentation says new Projects enable workflows that set Status to Done when an issue/PR closes or when a PR merges. Other workflows can auto-add matching items or archive items. Some workflows can also cause a source-state mutation, such as closing an issue when a Project status changes. That means automation direction matters: “source event updates planning field” is usually safer than “planning field mutates source resource” unless the team explicitly owns that policy.

8. Read-only inspection before you build anything

gh auth status --active --hostname github.com

gh project list --owner YOUR_LOGIN --format json

gh project view PROJECT_NUMBER --owner YOUR_LOGIN --format json

gh project field-list PROJECT_NUMBER --owner YOUR_LOGIN --format json

gh project item-list PROJECT_NUMBER --owner YOUR_LOGIN --limit 100   --format json

The gh project family requires Project authorization. The CLI manual currently documents project as the minimum scope for the command group; GitHub’s API guide distinguishes read:project for queries from project for mutations. Do not widen an employer-managed credential merely to complete a lab—use a personal disposable identity or the web UI instead.

# Current Projects v2 REST read, explicit 2026 API version
gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   "/users/YOUR_LOGIN/projectsV2?per_page=100" --paginate

GitHub now documents Projects v2 REST endpoints for projects, fields, items, and views under API version 2026-03-10. The Projects automation guide still documents GraphQL extensively, so both interfaces are legitimate current platform surfaces.

9. DevOps connection: planning is an observability layer for delivery work

A useful Project makes backlog, implementation, review, and release intent visible without manufacturing a second truth. In a delivery system, the Project says “we plan this work for Iteration 3 and consider it In Progress”; the pull request says whether code is actually reviewed/merged; Actions checks say whether validation passed; a deployment system says whether production changed. Reliability comes from joining these signals, not collapsing them into one status column.

10. Lesson summary

Projects are hosted planning resources made of items, fields, views, workflows, and access controls. Items can reference issues/PRs or exist as drafts. Views are projections of one model. Project Status and Priority are planning data, while issue/PR/commit/deployment state remains authoritative in its own resource.

Knowledge check

Authoritative references

• About Projects
• Creating a project
• Understanding fields
• About iteration fields
• Customizing views
• Built-in Project automations
• Managing access to Projects
• Managing Project visibility
• Adding a Project to a repository
• gh project
• REST API for Projects
• Using the API to manage Projects
• REST API versions