Projects and Issue Management
GitHub Projects is a table, board, and roadmap view layered over issues and pull requests, with custom fields and built-in automation. It keeps planning in the same place as the work, so status reflects reality instead of living in a separate tracker that someone has to remember to update.
The payoff comes from the live link between a project item and its source issue or PR, plus the no-code workflows that keep the board honest. Lean on those and the board maintains itself; skip them and you are back to manual bookkeeping that quietly drifts out of date.
The Tables-Based Model
The current Projects model is built on items with custom fields — a status, an iteration, single-select categories, numbers — that you view as a Table, a Board, or a Roadmap. The same underlying items render in every view, so a sprint board and a date-driven roadmap are two windows onto one dataset rather than separate copies to keep in sync.
This is distinct from the older "classic" Projects boards, which GitHub is sunsetting. New work should be built on the current model, not the deprecated one.
Linking Issues and PRs
An item added from an issue or pull request pulls its state live from the source. When the issue is closed or the PR merges, the item reflects that without anyone editing the project, so the board does not lie about what is done — provided the workflows below are switched on.
Built-in Workflows
The automation tab offers no-code workflows: set an item's status to Done when its issue closes, auto-add any item matching a filter, and auto-archive items in a terminal state. These are what keep the board truthful with zero manual upkeep. Without the close-to-Done workflow, an issue can close while its project status sits at "In progress" indefinitely.
Iterations and Roadmaps
An Iteration field models sprints as repeating time windows, which the Board and Table views can group by. The Roadmap view plots items against dates, giving a calendar-style picture of date-driven work that a board cannot show. Iterations answer "which sprint," milestones answer "which release" — they are complementary, not interchangeable.
Cross-Repo and Org Projects
An organization-level project can span many repositories, which is the only sane way to track an initiative that crosses repo boundaries. Labels and milestones are per-repo, so a cross-repo effort tracked with them has no single view. The project's filter syntax then lets you slice that combined set of items by field.
- Tracking status in a custom field without the close-to-Done workflow — an issue closes but its project status stays "In progress" and the board misleads everyone.
- Adding every issue to the project by hand — without the auto-add workflow, items go missing and the board no longer reflects all the work.
- Building on classic Projects boards — they are deprecated, so the work lands on a model GitHub is sunsetting.
- Tracking a cross-repo initiative with labels and milestones — they are per-repo, so the initiative has no single combined view.
- Never archiving completed items — the board grows until it is unusable and the views slow down.
- Enable the built-in "item closed → set Status to Done" and auto-archive workflows so the board stays truthful with no manual upkeep.
- Use an org-level project to span repositories for any initiative that crosses repo boundaries.
- Add an Iteration field for sprint planning and use the Roadmap view for date-driven work.
- Use the auto-add workflow with a filter so new matching issues land on the board automatically.
- Keep custom fields minimal — status, priority, iteration — so the board stays scannable.
Knowledge Check
Why does automation keep a project board more honest than manual status updates?
- Workflows set status from the live issue/PR state, so a closed issue moves to Done on its own instead of drifting
- Automation quietly hides away any board item that has not been touched or updated by anyone in the last several days
- Manual edits to a field are blocked entirely once board automation is switched on
- Automation deletes any item outright whenever its recorded status looks wrong
When does an org-level cross-repo project beat labels and milestones?
- When an initiative spans multiple repos — labels and milestones are per-repo, so only an org project gives one view
- When all of the work for the initiative already lives inside a single repository and never once leaves it for another
- When you only ever need to track items as open versus closed
- Never, since labels can already span repos natively across an org
What distinguishes an Iteration field from a milestone?
- An iteration models repeating sprint windows for planning, while a milestone groups work toward a specific release
- They are the same underlying feature exposed under two different names
- A milestone repeats on a fixed recurring schedule, while an iteration is just a single one-off target with no repetition
- Iterations are scoped per-repo while milestones apply org-wide across repos
Why avoid building new planning on classic Projects boards?
- Classic boards are deprecated and being sunset, so new work belongs on the current tables-based model
- Classic boards cannot hold more than ten items per column, so a busy backlog overflows
- Classic boards do not support issues at all, holding only pull requests, so any plan built on issues cannot live there
- There is no real difference between the two; both remain fully current today and receive the same ongoing support
You got correct