Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Issues, Projects and Discussions

GitHub Projects: Tables, Boards and Roadmaps

Plan and track work with GitHub Projects: create a project, add issues and pull requests, use custom fields, switch between table, board and roadmap views, group, filter and automate.

Issues tell you what needs doing; labels and milestones classify it. GitHub Projects is the planning layer on top: a flexible, spreadsheet-like workspace where you arrange issues and pull requests from many repositories, add your own fields (status, priority, size, iteration), and look at the same data as a table, a Kanban board or a timeline. It stays in sync with the issues themselves: change a status in the project, and the card moves everywhere; close an issue, and the project knows.

The current "Projects" is a different product from the older "classic" project boards, which have been retired. Everything here refers to the current version.

Creating a project

Projects belong to a user or an organization (not to a single repository, although you can link them to repositories). Open your profile or organization, choose the Projects tab, then New project. Pick a template, such as Table, Board, Roadmap, Team planning or Bug tracker, or start blank. You can also create one on the CLI: gh project create --owner octo-org --title "Website relaunch".

Visibility is separate from repository visibility: a project can be private (only people you invite) or public, and it can contain items from private repositories that only authorized people will see in detail.

Adding items

An item is an issue, a pull request, or a draft (a title-only note that lives only in the project). Add items by:

  • Pressing + at the bottom of a table, or Add item on a board column, and typing # to search a repository's issues.
  • Pasting an issue URL.
  • Choosing Add to project from the sidebar of an issue or PR.
  • Automatically, with a workflow (below).
  • Converting a draft to a real issue in a chosen repository.

One issue can sit in several projects, and each project keeps its own field values.

Fields

Every item has built-in fields (title, assignees, labels, milestone, repository, reviewers, linked pull requests) plus custom fields you create from + in the table header:

Type Use
Text Short notes, links
Number Story points, estimates
Date Target or due date
Single select Status (Todo, In progress, Done), Priority (P0, P1, P2)
Iteration Sprints: a series of fixed-length periods (for example two weeks), with the current one highlighted

The Status single select drives the board columns. You can rename its options, add In review or Blocked, and give options a color and description.

Views

A project can have many views, each a saved combination of layout, filter, sort and grouping. The tabs along the top are views; New view adds one.

  • Table: one row per item, one column per field. Edit inline, drag to reorder, group by any field (for example by Assignee or Iteration), show a count or sum in each group.
  • Board: Kanban columns by a single-select field, usually Status. Drag a card to change its value; set column limits (a WIP limit) to avoid overload.
  • Roadmap: a timeline using date or iteration fields, which is good for communicating plans to stakeholders. Zoom by month, quarter or year, and drag bars to change dates.
JS Stand-in: group a table into board columns

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Filtering, sorting and slicing

The filter bar uses the same qualifier style as issue search, plus field names:

TEXT
status:"In progress" assignee:@me
label:bug -status:Done
iteration:@current
priority:P0,P1
-is:closed
no:assignee

@me and @current (the current iteration) are special values. The Slice by option shows a sidebar panel where clicking a value, such as an assignee, filters the table instantly. Group, sort and filter changes are shown with a dot until you save them to the view, so you can explore without disturbing everyone else.

JS Stand-in: filter and sum

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Automation

Built-in workflows (project ... menu > Workflows) react to events without writing code:

  • Item added to project: set Status to Todo.
  • Item closed: set Status to Done.
  • Pull request merged: set Status to Done.
  • Auto-add to project: automatically add new issues or PRs from a repository that match a filter, such as is:issue label:bug.
  • Auto-archive items: archive items closed for more than a given time, so boards stay tidy.

For anything custom, you can use GitHub Actions with the Projects GraphQL API (see the Administration and API chapter), or the CLI: gh project item-add, gh project item-edit, gh project field-list.

Insights

The Insights tab draws charts from your data: a burn-up of items per status over time, or a chart grouping by assignee or iteration. Configure the X axis, grouping, and filter, then save the chart. It is a good way to see throughput without exporting to a spreadsheet.

A simple way to start

  1. Create a project from the Board template.
  2. Add a Priority single select and an Estimate number.
  3. Turn on the auto-add workflow for your main repository, and pull request merged to Done.
  4. Hold a short weekly meeting looking at the In progress column, then update.

Resist adding fields nobody will keep current; three or four are plenty.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a draft item in a project?

    Drafts are lightweight notes without a repository until you convert them.
  2. 2. Which field type lets you model sprints?

    Iteration fields define repeating periods such as two-week sprints.
  3. 3. Which view type shows items on a timeline using dates or iterations?

    Roadmap is the timeline layout.
  4. 4. How can new issues from a repository be added to a project automatically?

    The Auto-add workflow adds matching issues and pull requests as they are created.

Summary

  • Projects is a planning workspace across repositories; its items are issues, pull requests or drafts.
  • Custom fields (single select, number, date, iteration) add the data you plan with.
  • Table, board and roadmap views show the same items differently; filters, grouping and slices explore them.
  • Built-in workflows and the CLI automate status changes; keep fields few and current.

Next: Discussions, Wikis and Community Features