Issues are great for recording individual tasks, but once a project has fifty of them, you need a way to see the big picture. What's being worked on right now? What's blocked? What's planned for next month? GitHub Projects answers those questions.
A project is a flexible planning space that collects issues and pull requests, from one repository or many, and shows them as a board with columns, a table like a spreadsheet, or a roadmap on a timeline. Because it's built from real issues and pull requests, it updates itself as work happens: when a pull request merges and closes an issue, the card moves to Done.
In this lesson you'll create a project, add work to it, customise fields and views, automate the boring parts, design issue forms that collect the right information, and use Discussions for conversations that aren't tasks.
Creating a project and adding items
Open your profile or organisation, choose the Projects tab and click New project. Pick a template such as Board or Team planning, or start blank.
Add items by typing # in the bottom row and choosing an issue or pull request, or by pasting an issue's URL. You can also add a draft item, a quick note that's not an issue yet, and convert it to a real issue later. One project can hold work from many repositories, which suits teams with a separate front end and back end.
Views: board, table and roadmap
Each project can have several views, shown as tabs:
| View | Looks like | Good for |
|---|---|---|
| Board | Columns of cards (To do, In progress, Done) | Daily stand-ups and seeing flow |
| Table | Rows and columns, like a spreadsheet | Sorting, filtering and bulk edits |
| Roadmap | Bars on a timeline | Planning dates and releases |
Each view can filter (label:bug assignee:@me), group (by assignee or milestone) and sort. A team might keep a "My work" table, a "Bugs" board and a "Q3 roadmap", all showing the same items in different ways.
Custom fields and automation
Besides an issue's own labels and assignees, a project can add custom fields: a Status list, a Priority of High, Medium or Low, a Size number, a Date, or an Iteration for sprints. They belong to the project, so they don't clutter the issue itself.
Under the menu's Workflows, switch on built-in automation:
- Item added: set Status to To do.
- Pull request merged and Item closed: set Status to Done.
- Auto-add: add new issues from a repository that match a filter, such as
label:bug.
Issue forms and Discussions
An issue form is a YAML file in .github/ISSUE_TEMPLATE/ that turns "New issue" into a form with required fields, drop-down menus and checkboxes. It makes bug reports consistent, because nobody can forget the steps to reproduce.
Discussions, switched on in a repository's settings, is a forum for questions, ideas and announcements that aren't actionable tasks. Questions can have an answer marked as accepted. Keeping "How do I...?" posts in Discussions keeps the issue list focused on real work, and a good discussion can be converted into an issue when it becomes one.
GitHub Projects Syntax
Project filters and CLI
is:issue is:open label:bug
assignee:@me status:"In progress"
priority:High -label:wontfixgh project list --owner samlee
gh project item-add 3 --owner samlee --url https://github.com/samlee/portfolio/issues/14GitHub Projects Summary
- GitHub Projects collects issues and pull requests from one or more repositories into a planning space.
- Board, table and roadmap views show the same items in different ways, with filters and grouping.
- Custom fields such as Status, Priority, Size and Iteration belong to the project.
- Built-in workflows move items automatically when they're added, closed or merged.
- Issue forms collect consistent reports; Discussions hold questions and ideas.
GitHub Projects Examples
Each example shows the code, the output it produces and what each part does.
A board for a small team
Project: Portfolio relaunch View: Board, grouped by Status
To do (3) In progress (2) Done (4)
#21 Dark mode #18 Contact form @ben #12 Hero section
#23 Blog page #19 Fix nav (PR) @sam #14 Footer links
Draft: Add favicon #15 Mobile menu
#16 Image sizesAnyone can see at a glance what's planned, who is
working on what, and what's finished. When PR #19
merges, its card moves to Done automatically.Line-by-line explanation
- Line 1The project title and current view.
- Line 3Columns come from the Status field.
- Line 6A draft item can be turned into an issue later.
An issue form
name: Bug report
description: Something isn't working
labels: ["bug"]
body:
- type: textarea
id: steps
attributes:
label: Steps to reproduce
placeholder: "1. Open the menu 2. Click Blog"
validations:
required: true
- type: dropdown
id: browser
attributes:
label: Browser
options: [Chrome, Firefox, Safari, Edge]New issue > Bug report
Steps to reproduce * [ text box ]
Browser [ Chrome v ]
Submitting adds the "bug" label automatically.Line-by-line explanation
- Lines 1 to 3The form's name, description and automatic label.
- Lines 5 to 11A required text area for reproduction steps.
- Lines 12 to 16A drop-down menu, so everyone picks from the same list of browsers.
Adding work from the terminal
gh issue create --title "Add dark mode" --label enhancement
gh project item-add 3 --owner samlee --url https://github.com/samlee/portfolio/issues/21https://github.com/samlee/portfolio/issues/21
Added itemLine-by-line explanation
- Line 1Create an issue; GitHub prints its address.
- Line 2Add it to project number 3 owned by samlee.
Common GitHub Projects Mistakes
Status that never changes
Cards stay in "In progress" for weeks after the work mergedTurn on the "Pull request merged" and "Item closed" workflowsUsing issues for questions
Issue #88: "How do I install this on a Mac?"Discussions > Q&A: "How do I install this on a Mac?"Questions clutter the task list and are hard to find again in closed issues.
Labels for everything
Labels: priority-high, size-3, sprint-7, status-doingProject fields: Priority, Size, Iteration, StatusFields can be sorted, filtered and charted; dozens of labels can't.
GitHub Projects in Real Projects
Projects in real teams
Small teams often run their whole planning on a single GitHub Projects board, avoiding a separate tool. Open-source projects publish public roadmaps so users can see what's coming, and use Discussions as their community forum. Large organisations create projects that span dozens of repositories, with iterations for two-week sprints and charts showing how much work is completed each cycle.
GitHub Projects FAQ
Can one GitHub project track issues from several repositories?
Yes. A project belongs to a user or organization rather than to a single repository, so you can add issues and pull requests from any repositories you can access. Add a Repository column or group by repository to see where each item lives.
Can I make a GitHub project public?
Yes. In the project's settings you can set its visibility to public or private. A public project is visible to anyone, but items from private repositories are still only shown to people who have access to those repositories.
What is the difference between milestones and projects?
A milestone belongs to one repository and groups issues towards a single goal or release, with a simple progress bar. A project can span many repositories and gives you custom fields, several views and automation. Many teams use both: milestones for releases and a project for day-to-day planning.
Can I use GitHub Projects as a personal to-do list?
Yes. Create a project under your own account and add draft items for quick notes and issues for real work across your repositories. A simple board with To do, In progress and Done columns works well for one person.
How do I hide finished items without deleting them?
Archive them. Archived items disappear from the project's views but keep their history, and you can restore them later. A built-in workflow can archive items automatically once they meet conditions you set, such as being closed.
GitHub Projects Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Complete the folder where issue forms are stored.
.github//bug_report.ymlWhich project view shows work as columns of cards?
Where should a question like "How do I install this?" usually go?
What does the "Pull request merged" workflow do?
Why use a custom Priority field instead of priority labels?
GitHub Projects Quiz
5 questions to check what you learned.
What can a GitHub project contain?
- Issues, pull requests and draft items, from one or more repositories
- Only commits
- Only issues from a single repository
- Only files
What is a draft item?
- A closed issue
- An unpublished release
- A draft pull request
- A quick note in a project that can later be converted into a real issue
Which view is best for planning dates on a timeline?
- Board
- Roadmap
- Table
- Discussions
What advantage do issue forms have over a blank issue?
- They're private
- They close automatically
- Required fields and menus make every report include the information you need
- They skip review
What does an Iteration field help a team do?
- Plan work in fixed time periods such as two-week sprints
- Count commits
- Merge pull requests
- Sync forks