imshubh.

Product leader · IEEE Senior Member · CMU MSE board member

Connect↗
← GitHub articles

A roadmap kept in a separate spreadsheet drifts from the issues it is supposed to describe. Keeping planning next to the code avoids that split.

Roadmaps Next to Your Code: GitHub Projects for Platform Teams

How to run a roadmap in GitHub Projects using table, board, and roadmap views, custom fields, and built-in automations.

Shubham Anandani··3 min read

Problem

External roadmap tools fall out of date because they are not connected to issues and pull requests. GitHub Projects sits alongside issues and PRs and gives each team a view suited to its question: a prioritized backlog, the current iteration board, or a timeline roadmap.

Options and trade-offs

  • Table view: dense and good for prioritization. It needs consistent field values.
  • Board view: a status-based layout for iteration planning. It works best with work-in-progress limits.
  • Roadmap view: a timeline across dates or iterations. It suits communicating schedules to others.
  • Built-in workflows: add items, set status, and archive without code. They are limited compared with custom automation.
  • Insights: charts for status and progress. Useful for a quick read, not a full reporting tool.

My take

Use one organization-level project for the platform roadmap, keep tactical bug work out of it, and save a small set of views that answer the questions people actually ask.

Decision lens: review latency and team workload.

Example setup: a platform roadmap project with Priority, Estimate, Iteration, and Owner fields, auto-add filters for the relevant repositories, and three saved views: backlog by priority, the current iteration board, and the quarter roadmap.

Template

Project fields: a single-select Priority field, a number field for Estimate, and an iteration field.

Views: Table for the backlog, Board for the current iteration, and Roadmap for milestones.

Workflows: auto-add issues with a chosen label, set new items to Todo, and archive items that have been Done for a set period.

Project README: link the saved views and describe the naming and labeling rules.

Checklist

  1. Create an organization project and define the fields.
  2. Save table, board, and roadmap views.
  3. Configure auto-add and status workflows.
  4. Add milestone markers to the roadmap view.
  5. Document label and ownership conventions.
  6. Set work-in-progress limits on the board.

Common mistakes

  • Mixing bug triage with strategic planning in one project. Split them.
  • Not saving views, so collaborators lose context.
  • Skipping automation, which lets status drift from reality.

Where this doesn't apply

  • Teams required to use an external project management system. Mirror the data through the API if needed.

How to get involved

  • Good first issue: propose a saved view that would improve backlog triage.
  • Discussion: what fields should the roadmap track?

Sources (accessed 2026-10-18)

  • About Projects: https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects. Views, fields, automation, and insights.
  • Quickstart for Projects: https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects. Creating views, fields, and workflows.
  • Roadmaps generally available: https://github.blog/changelog/2025-03-22-roadmaps-in-projects-are-now-generally-available/. Roadmap view status and markers.

---