GitHub Projects, Labels, Milestones and Insights: Project Tracking (GH-900)
GitHub project tracking is the set of features a team uses to plan and follow work on GitHub: Projects (a table, board or roadmap of issues and pull requests from many repositories), labels and milestones inside each repository, built-in workflows that update items automatically, saved replies and assignees for communication, and insights charts and status updates for progress. This lesson covers the GitHub Foundations (GH-900) project tracking skills: choosing a layout, configuring fields, labels, milestones and workflows, using saved replies and assignees, and reading project insights.
On this page9 sections
- Describe what a GitHub project is, who owns it and how its built-in fields stay in sync with issues and pull requests
- Choose between the table, board and roadmap layouts and the right custom field type, including iteration fields
- Use draft issues, bulk add and the auto-add and auto-archive workflows, and predict what the default workflows do
- Decide between labels, milestones and projects, and identify who can apply or create labels
- Use saved replies and assignee filters such as assignee:@me to streamline communication
- Configure current and historical insights charts and post project status updates to report progress
What GitHub Projects is and where it lives
GitHub Projects is an adaptable planning tool that holds issues, pull requests and draft issues as items in a table, board or roadmap, with custom fields and saved views on top. A project is owned by a personal account or an organization, not by a repository, so one project can gather work from many repositories at once.
A project stays in sync with the work it tracks. Built-in fields such as Title, Assignees, Labels, Milestone, Repository, Reviewers and Linked pull requests are the issue or pull request's own data: change an assignee or label in the project and the issue changes in its repository too, and the reverse. Custom fields such as Status, Priority or Points are project data and live only in the project.
- Items: issues and pull requests from any repository you can access, plus draft issues.
- Views: saved combinations of a layout, filter, sort, grouping and visible fields, each shown as a tab.
- Visibility and access: a project can be public or private, and people or teams get read, write or admin access to it separately from repository access.
- Templates and linking: an organization can save projects as templates, and a project can be linked to repositories so it appears in their Projects tab.
This lesson describes the current Projects experience, not the older "Projects (classic)" boards.
Table, board and roadmap layouts
Every project view uses one of three layouts: table for dense detail, board for flow between stages, and roadmap for work across time. Layout is a property of the view, so the same items can be a table in one tab and a board in another.
| Layout | What it shows | Driven by | Typical use |
|---|---|---|---|
| Table | A spreadsheet-style grid, one row per item, with fields as columns | Any fields you show, sort, group or slice by | Triage, bulk editing, reviewing many fields at once |
| Board | Cards in columns, moved by drag and drop (kanban) | A column field: a single select or iteration field such as Status | Watching items move from Todo to In progress to Done |
| Roadmap | Each item as a bar on a timeline, zoomable by month, quarter or year | A start and a target field, each a date or iteration field | Spotting overlaps and planning dates across a release or quarter |
A table can show a date as a value but does not draw it; only the roadmap places items as bars between two dates. Other field types cannot define columns, because they have no fixed set of values. Board columns can also show a field sum (for example total Points) and an item limit to flag overloaded stages.
Configuring fields, iterations and views
You configure a project mainly through its custom fields and its views. Pick the field type by what the value must do:
| Field type | Holds | Choose it when |
|---|---|---|
| Text | Free text | Notes or short descriptions with no fixed values |
| Number | A number | Estimates or points you want to sort, sum or chart |
| Date | One calendar date | Due or start dates, roadmap bars |
| Single select | One value from a fixed list of options | Status, priority, size: fixed choices that can become board columns |
| Iteration | One of a repeating series of time blocks | Sprints or cycles, with optional breaks and a "current" block |
An iteration field has a start date and a duration in days or weeks, and generates consecutive iterations. You can insert a break (for example over holidays) so no iteration covers that gap. Filters understand iteration-relative values such as iteration:@current, @next and @previous, so a view always shows the block in progress without being edited each sprint. Other field types have no dates behind them, so they offer no breaks and no automatic current sprint.
A view saves a layout plus its filter, sort, group-by, slice-by and visible fields. Unsaved changes are marked on the tab until you save them, and each view gets its own tab across the top of the project.
Draft issues and adding items
A draft issue is an item that exists only inside the project: it has a title, a Markdown body, assignees and custom field values, but no repository. It is the right way to capture an idea before deciding where the work belongs.
Because labels and milestones are repository objects, a draft issue cannot have labels or a milestone until you convert it into an issue in a chosen repository. Converting keeps the item in the project and turns it into a real issue that can then be labelled, given a milestone and linked to pull requests.
Items get into a project in several ways:
- Paste an issue or pull request URL, or type
#in the add-item row to search a repository. - Bulk add from a repository: pick a repository, filter (for example
label:bug) and add the matching issues and pull requests in one step. - From the issue or pull request itself, using the Projects section of its sidebar.
- Automatically, with the auto-add workflow (next section) for new and updated items.
Labels and milestones
Labels categorise issues, pull requests and discussions inside one repository; milestones group a repository's issues and pull requests toward a goal with a due date. Both are repository-scoped, which is the key difference from a project.
| Label | Milestone | Project | |
|---|---|---|---|
| Scope | One repository | One repository | Many repositories (user or organization owned) |
| Per item | Many labels | At most one milestone | An item can be in several projects |
| Dates and progress | None | Optional due date and a percentage complete | Date and iteration fields, roadmap, insights charts |
| Best for | Filtering and categorising (bug, docs, priority) | A release or goal inside one repository | Planning and tracking across repositories and teams |
Default labels. New repositories start with a default set: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question and wontfix. good first issue marks beginner-friendly work and feeds the repository's contribute page for first-time contributors; help wanted only signals that maintainers would welcome help. Organization owners can customise the default labels copied into the organization's new repositories, but each copy is still an ordinary repository label.
Who can do what. Anyone with triage access can apply and dismiss labels and manage issues and pull requests without being able to push code; creating, editing and deleting labels needs write access. Milestones are created and edited by people with write access.
Milestones and releases are different things. A milestone tracks planned work toward a due date; a release packages shipped software at a Git tag. Labels carry neither a due date nor progress.
Project workflows and automation
Project workflows are built-in automations that update items when something happens, with no code. Two are enabled by default in every new project: when an item is closed, or a pull request is merged, its Status is set to Done.
Other built-in workflows can be switched on and configured in the project's Workflows page, for example setting a status when an item is added or reopened, or when a review approves or requests changes. Two deserve attention:
- Auto-add to project watches a repository and adds items that match a filter (such as
is:issue label:bug). It only acts on items created or updated after it is enabled; it never sweeps up existing items. Bring in an existing backlog once with the bulk add-from-repository option. - Auto-archive items archives items that match criteria (for example closed items not updated for a while), keeping views small. Archived items can be restored.
For anything the built-in workflows cannot do, use GitHub Actions with the GraphQL API to automate projects, for example setting a custom field when a pull request opens.
Saved replies and assignees
Saved replies are reusable comment texts stored in your personal account settings. You insert one from the comment toolbar in any issue, pull request or discussion, in any repository or organization where you can comment. They are private to you: organization members do not share or see each other's saved replies, and they are not stored in a repository. They are not the same as templates:
| Saved reply | Issue or pull request template | |
|---|---|---|
| Who uses it | You, when you write a comment | Anyone opening a new issue or pull request |
| Where it lives | Your personal account settings | Files in the repository (for example .github) |
| What it fills | A comment box | The body of a new issue or pull request |
Assignees make ownership explicit, and in a project they become a way to route and see work. The Assignees field in a project is the issue's real assignee list, so assigning in the project assigns the issue. Useful filters:
assignee:@me:@meresolves to whoever is viewing, so one shared view shows every person their own items.-assignee:@me: a leading hyphen negates a filter, so this shows everything not assigned to you.no:assignee: items nobody owns yet, a good triage view.reviewers:@me: pull requests where you are a requested reviewer, which is different from being assigned.
Grouping or slicing a table or board by Assignees shows each person's workload at a glance. The basics of assigning issues themselves (and how assignees differ from @mentions) are covered in the collaboration tools lesson.
Project insights: tracking progress
Project insights are configurable charts built from a project's items, used to track progress and spot bottlenecks. There are two kinds, and the choice depends on whether you need a snapshot or a trend:
| Current chart | Historical chart | |
|---|---|---|
| Shows | Items as they are now | How items changed over time |
| X-axis | A field such as Status, Assignees or Iteration | Time |
| Example | Points per status in this sprint | The default burn up chart: completed versus total over time |
Each chart has a layout (bar, column, line, stacked area and similar), an X-axis, and a Y-axis that is either a count of items or the sum, average, minimum or maximum of a number field. A current chart can also group each bar by a second field; a historical chart always has time on the X-axis. Summing a Points field weighs a large task more than a small one; counting items treats them equally. A filter narrows the chart with the same syntax as views, for example iteration:@current for the sprint in progress (@next is the upcoming one) or a Release field value for one release.
Because a project spans repositories, an insights chart filtered to a release can show progress across several repositories in one place, which a single milestone cannot do.
Project status updates
A project status update is a short report on the project's overall health. It records a status (On track, At risk, Off track, Inactive or Complete), optional start and target dates, and a Markdown message. People with write access to the project can post one.
The latest update appears in the project's side panel and header and in lists of projects, so anyone opening the project or browsing the organization's projects sees whether it is on track. Earlier updates are kept as a history. Only a status update carries a health status that appears in the project lists.
Tip. Questions are short scenarios that ask which project feature, layout, field type, filter or chart setting fits a stated need. Expect near-twins: table, board or roadmap; single select, text, number or labels for board columns; an iteration field or a single select of sprint names; a milestone, a label, a release or a project; good first issue or help wanted; triage or write access for labels; a saved reply or a template; assignee:@me, -assignee:@me, no:assignee or reviewers:@me; current or historical charts; count or sum on the Y-axis; @current or @next. Some items check what happens automatically (built-in workflows, two-way sync of assignees, what auto-add does not do) or what a draft issue cannot have. Harder items combine two facts, and a few are select-TWO; read constraints such as across several repositories, least access, or a single view for everyone.
- A project is owned by a user or organization and can hold issues, pull requests and draft issues from many repositories; built-in fields such as Assignees, Labels and Milestone edit the issue itself.
- Table for detail, board for flow, roadmap for time: board columns come from a single select or iteration field, roadmap bars from start and target date or iteration fields.
- Pick field types by behaviour: single select for fixed choices, number for values you sum, iteration for repeating sprints with breaks and @current/@next filters.
- Draft issues live only in the project and need converting to an issue in a repository before they can have labels or a milestone.
- Labels and milestones are repository-scoped; a milestone has a due date and percent complete; a project tracks work across repositories.
- good first issue feeds the contribute page; triage can apply labels without pushing code, write is needed to create them.
- New projects set Status to Done when items close or pull requests merge; auto-add only catches new or updated items, so bulk add the existing backlog.
- Saved replies are personal, reusable comments for issues, pull requests and discussions; templates prefill what others open.
- assignee:@me shows each viewer their own work from one view; a leading hyphen negates; no:assignee finds unowned items.
- Current charts are snapshots, historical charts (default burn up) are trends; the Y-axis can count items or sum a number field; status updates report project health.
Frequently asked questions
What is the difference between a GitHub project and a milestone?
A milestone belongs to one repository and groups that repository's issues and pull requests toward a goal with an optional due date and a percentage complete. A GitHub project is owned by a user or organization, can hold issues, pull requests and draft issues from many repositories, and adds custom fields, table, board and roadmap layouts, automation and insights charts. Use a milestone for a release inside one repository and a project to plan or track work across repositories.
Which layouts does GitHub Projects offer?
GitHub Projects offers three layouts per view: table, a spreadsheet-style grid of items and fields; board, kanban cards in columns set by a single select or iteration field such as Status; and roadmap, which draws each item as a bar on a timeline between a start and a target date or iteration field. The same items can appear in different layouts in different saved views.
What is an iteration field in GitHub Projects?
An iteration field is a custom project field that divides time into repeating blocks, such as two-week sprints, from a start date and a duration. You can add breaks so no iteration covers a holiday, and filter views or charts with iteration:@current, @next or @previous so they always show the right sprint. A board can use an iteration field as its columns.
Does the auto-add workflow add existing issues to a project?
No. The GitHub Projects auto-add workflow only adds items that are created or updated after it is enabled and match its filter, such as is:issue label:bug. Issues that already exist are not added, even if you turn the workflow off and on again. Add an existing backlog once with the project's bulk add-from-repository option, using the same filter.
What are saved replies on GitHub?
Saved replies are reusable comment texts stored in your personal GitHub account settings. You can insert one into a comment on any issue, pull request or discussion, in any repository or organization, from the comment toolbar. They are private to you and are not shared with organization members, unlike issue and pull request templates, which are repository files that prefill new issues and pull requests for everyone.
What is the difference between current and historical charts in project insights?
In GitHub project insights, a current chart shows the project's items as they are now, split by a field such as Status or Assignees, while a historical chart shows how items changed over time, with time on the X-axis. The default insights chart is a historical burn up chart. Either kind can count items or sum, average, or take the minimum or maximum of a number field, and can be filtered, for example to iteration:@current.
Source
This lesson covers the "Manage projects with GitHub" domain of the official GH-900 exam guide. Vendors revise their guides — check the source for the current version.
Sign up free to mark lessons complete, bookmark topics and track your exam readiness.