Most engineering teams already have their code on GitHub. Their project tracking lives somewhere else entirely.
That split creates real friction. Knowing how to use GitHub Projects fixes it by keeping your issues, pull requests, sprint planning, and backlog management inside the same platform where the work actually happens.
This guide covers everything from creating your first project board to configuring custom fields, workflow automation, and the built-in Insights charts. By the end, you’ll have a complete picture of how to run your team’s agile project management directly inside GitHub, without a separate tool.
What Is GitHub Projects?
GitHub Projects is a built-in project management tool inside GitHub that organizes issues, pull requests, and draft items into a structured, flexible board. It operates at either the repository or organization level, making it useful for solo developers, open source maintainers, and full engineering teams.
The current version, called ProjectsV2, launched in 2022 and replaced the older classic Projects experience. The two are not the same thing. ProjectsV2 added table views, custom fields, roadmap timelines, and iteration support, none of which existed in the original.
GitHub now hosts over 180 million developers globally (Octoverse 2025). That scale puts GitHub Projects in front of more engineering teams than almost any other project management tool available today.
How GitHub Projects Differs from GitHub Issues
GitHub Issues are individual work items: a bug report, a feature request, a task. They live inside a repository.
GitHub Projects is the layer on top. It pulls issues and pull requests from one or more repositories into a single organized workspace where you can group, filter, sort, and track progress across all of them.
Think of Issues as the raw data and Projects as the interface for managing that data. You need both, but they do different jobs.
Organization-Level vs. Repository-Level Projects
Repository-level projects attach to a single repo and are visible from that repo’s main navigation. Best for solo developers or small teams working on one product.
Organization-level projects sit at the org level and can pull issues from every repository inside that organization. This is where the tool gets genuinely useful for larger teams managing multiple products or services in parallel.
| Level | Scope | Best For |
|---|---|---|
| Repository | Applies to a single repository only | Solo developers, small teams, open-source projects |
| Organization | Applies across all repositories in an organization | Multi-team engineering orgs, cross-product planning, enterprise workflows |
How Do You Create a GitHub Project?
You can create a project from 3 places: your personal profile, an organization’s main page, or directly from a repository’s “Projects” tab. The starting point determines the default scope, but you can connect additional repositories later.
Once you start, GitHub asks you to pick a layout. Board, Table, and Roadmap are the 3 options. You can switch between all 3 at any time without losing data, so the initial choice matters less than it seems.
Step-by-Step: Creating Your First Project
- Go to your profile or organization page and click the “Projects” tab
- Click “New project”
- Choose a starting template or a blank layout
- Name the project and set visibility (public or private)
- Click “Create project”
- Link the project to one or more repositories from project settings
GitHub automatically creates 6 default fields on every new project: Title, Assignees, Status, Labels, Milestone, and Repository. You build on top of these with custom fields.
Project Visibility Settings
Public projects are visible to anyone on the internet, including people not logged into GitHub. Use this for open source work where external contributors need to see what’s being planned.
Private projects are visible only to members with explicit access. Use this for internal product work or anything that involves unreleased features.
One thing most people miss: visibility is set at the project level, not the repository level. A private repo can have a public project, and vice versa. Worth checking before you assume everything is hidden.
What Are the Three Views in GitHub Projects and When Do You Use Each?
GitHub Projects has 3 built-in view types: Board, Table, and Roadmap. Each one surfaces the same underlying data differently. You can create multiple saved views on a single project and switch between them depending on what you’re trying to see.
Switching views is non-destructive. It never changes the underlying item data, only how it’s displayed.
Board View
Board view is a kanban-style layout with columns driven by the Status field (Todo, In Progress, Done by default). Best for daily standup visibility and sprint tracking where the team needs to see what’s actively moving.
Teams using kanban-style boards report cutting time in process in half and reducing defects significantly compared to teams that don’t actively manage work in progress (Parabol, 2024).
- Drag items between columns to update status
- Group by any single-select field, not just Status
- Works best for teams practicing iterative development with short cycles
Table View
Table view is a spreadsheet-style layout. Every item is a row. Every field is a column. This is where bulk editing happens.
It’s the fastest way to update many items at once, apply filters across the full backlog, or review field coverage across all open work. Inline editing works directly in the cells without opening individual issues.
Best for: backlog grooming, sprint prep, and any situation where you need to see 50+ items and change field values without clicking into each one.
Roadmap View
Roadmap view is a timeline-based layout tied to date fields or iteration fields. Items appear as horizontal bars across a calendar grid. Best for release planning and milestone tracking where the team needs to see when things are scheduled relative to each other.
It requires at least one date field or iteration field to work properly. Without those fields configured, the roadmap view shows nothing useful.
| View | Layout | Best Use Case | Requires |
|---|---|---|---|
| Board | Kanban columns | Sprint tracking, work-in-progress (WIP) management, agile workflows | Status field |
| Table | Spreadsheet-style rows | Bulk editing, backlog grooming, data filtering and triage | No additional configuration |
| Roadmap | Timeline bars | Release planning, milestone tracking, long-term roadmap visualization | Date or iteration field |
How to Save and Name Custom Views
Every layout configuration you create can be saved as a named view. Click the view name at the top of the project to rename it. Add a new view with the “+ New view” button next to the existing view tabs.
Common patterns: one Board view for the current sprint, one Table view filtered to unassigned backlog items, one Roadmap view for the full quarter. All three live as tabs on the same project and take one click to switch between.
How Do You Add Items to a GitHub Project?
There are 4 ways to get items into a project: searching for existing issues or PRs, adding from a repository’s issue list in bulk, creating draft items directly inside the project, or configuring auto-add workflows that pull new issues in automatically.
Draft items are a useful but underused feature. They behave like placeholder issues inside the project and can be converted to real GitHub Issues with one click once the work is better defined.
Manual Adding vs. Auto-Add Workflows
Manual adding works well for small teams or projects where you want deliberate control over what enters the board. Use the “+ Add item” button at the bottom of any column or table row, then type to search for issues by title.
Auto-add workflows pull new issues into the project automatically when they match a filter you define, for example, any new issue labeled “bug” in a specific repository. This saves significant manual overhead on active projects with frequent issue creation.
GitHub Actions workflows can extend this further. For software development teams managing high-volume repositories, auto-add rules combined with Actions automations remove the need to manually triage every incoming item into the project board.
Adding Items in Bulk
From any repository’s Issues tab, you can select multiple issues with checkboxes and add them all to a project in one action. This is the fastest way to populate a new project from an existing backlog.
Select the issues, click the “Projects” dropdown in the bulk actions bar, and choose the target project. All selected items land in the project immediately with their existing labels, assignees, and milestones intact.
How Do Custom Fields Work in GitHub Projects?
Custom fields extend the default data model beyond the 6 fields GitHub creates automatically. There are 6 field types available: Text, Number, Date, Single select, Iteration, and Tracked by.
Each custom field you create appears as a column in Table view, an option in Board grouping, and a filter criterion in the filter bar. One field creation populates everywhere at once.
How to Set Up Iteration Fields for Sprints
Iteration fields are the closest thing GitHub Projects has to native sprint support. When you create an Iteration field, you define a start date, an iteration length (1 week, 2 weeks, etc.), and GitHub generates iterations automatically from that cadence.
Each iteration gets a name (Sprint 1, Sprint 2, etc.) that you can rename. Items assigned to an iteration appear in the Roadmap view as time-boxed blocks and can be filtered in any view using the filter bar syntax iteration:"Sprint 3".
Key limitation: GitHub Projects iteration fields do not generate velocity charts or burndown diagrams automatically. The Insights tab has basic burn-up charts, but teams running formal Scrum with sprint metrics will need supplementary tooling for deeper analytics.
How to Use Priority Fields Without Overcrowding the Board
Single select fields work well for priority levels. A typical setup uses 3-4 values: P1, P2, P3, and Backlog.
The mistake most teams make is adding priority as a Board grouping dimension on top of Status columns. That creates a cluttered matrix. Better approach: keep Board columns as Status only, and use priority as a filter or sort criterion in Table view when planning which items to pull into the next iteration.
Only 17% of teams report that their performance management systems actively support agile practices (KPMG). Getting field configuration right from the start reduces the noise that causes teams to abandon their boards within a few sprints.
How Do You Group, Filter, and Sort Items in GitHub Projects?
Grouping, filtering, and sorting are 3 independent operations that stack on top of each other. You can group by Assignee, filter by Label, and sort by a custom Number field all at once in the same view.
These combinations are what make GitHub Projects genuinely useful for teams larger than 3-4 people. Without them, the board is just a list.
Filtering with the Filter Bar
The filter bar at the top of every view accepts both field-based syntax and free text. Specific syntax examples:
assignee:username– show only items assigned to one personlabel:"bug"– show only items with the bug labeliteration:"Sprint 3"– show only items in a specific iteration-status:"Done"– exclude completed itemsrepo:org/repo-name– filter to one repository inside a multi-repo project
Filters save with the view. If you save a view called “My Work” with assignee:yourname -status:"Done", it opens with those filters pre-applied every time.
Grouping and Sorting Strategies
Grouping collapses items into collapsible sections based on a field value. In Table view, grouping by Assignee shows you each person’s workload at a glance. In Board view, grouping by Priority under existing Status columns creates a visual priority stack inside each column.
Sorting works well with Number fields. If you create a Story Points field (type: Number), you can sort Table view by story points descending to quickly identify the heaviest items in the backlog during sprint planning.
Practical tip: Create a separate saved view called “Sprint Planning” that groups by Iteration and sorts by Priority. Keep your main Board view ungrouped for daily standup. Two views, same data, completely different utility.
How Do GitHub Projects Workflows and Automation Work?
GitHub Projects has 5 built-in workflow triggers that handle the most common status update tasks automatically. These are configured from the project’s “Workflows” settings menu and require no code.
GitHub Actions runs over 5 million workflows daily as of 2025, up 40% year-over-year (CoinLaw). The built-in project workflows are a small subset of that broader automation ecosystem.
The 5 Built-In Workflow Triggers
Each trigger fires when a specific event happens to an item in the project:
- Item added to project – sets a default field value when any item enters the project
- Item reopened – moves the item back to a specified status column
- Item closed – moves the item to Done automatically
- Pull request merged – sets Status to Done when the linked PR merges
- Code changes requested – moves the linked PR back to In Progress
Enabling these removes the most common source of stale boards: items that are Done in the code but still showing as In Progress on the board because no one updated the status manually.
Auto-Archiving Closed Issues
The auto-archive workflow moves closed items out of the active project view after a set number of days. This keeps the board focused on work in progress without permanently deleting anything.
Archived items are still searchable and can be unarchived. The archive is not the same as deletion. Teams managing large repositories with hundreds of closed issues per sprint will notice an immediate improvement in board clarity once auto-archiving is enabled.
When to Use GitHub Actions Instead of Built-In Workflows
Built-in workflows cover event-based status updates well. They do not cover conditional logic, multi-step sequences, or cross-project updates.
Use GitHub Actions when you need to:
- Move items between two separate projects based on a label change
- Assign items to iterations automatically based on due date proximity
- Send notifications to Slack when a P1 item goes stale for more than 48 hours
- Sync project field values with an external system via the GraphQL API
The GitHub Actions build automation ecosystem has over 1,500 marketplace tools available (CoinLaw, 2025). Most common project automation needs have a published action that handles them without writing custom code.
How Do You Track Progress in GitHub Projects?
The primary progress indicator in GitHub Projects is the Status field. Items move through Todo, In Progress, and Done as work advances. That alone gives most small teams enough visibility.
For deeper tracking, the Insights tab generates charts directly from project data. No export needed, no third-party tool required at the basic level.
Current Charts vs. Historical Charts
Current charts show a snapshot of the project right now: items per assignee, items per label, items per iteration. Useful for workload balancing and sprint planning.
Historical charts track how items change over time. The default is a burn-up chart showing completed vs. remaining work across a date range. To build one, set the X-axis to “Time” in the chart configuration panel (GitHub Docs).
Historical charts are only available on GitHub Team and GitHub Enterprise Cloud plans, not on the Free tier.
Configuring the Insights Chart Axis
The Y-axis defaults to item count. If you use a Number field for story points, you can switch the Y-axis to sum that field instead, giving you a story-point burn-up rather than a raw issue count.
- Open Insights from the top-right icon on your project
- Click “Configure” on any chart
- Set Layout, X-axis, Y-axis, and Group by independently
- Save the chart with a custom name
Filtering the Insights chart works with the same syntax as the main project filter bar. A chart scoped to iteration:"Sprint 4" assignee:username shows one developer’s burn-up for a single sprint.
When Native Insights Are Not Enough
GitHub Projects does not natively generate burndown charts, velocity graphs, or cycle time analytics (GitHub community forums). Teams running formal Scrum with metric-driven retrospectives will hit this ceiling quickly.
Tools like Screenful connect to the GraphQL API and layer advanced analytics on top of GitHub Projects data, including forecasting charts based on historical throughput. That covers the gap without migrating to a heavier project management framework.
How Do You Manage GitHub Projects at the Organization Level?
Organization-level projects pull issues from every repository inside that organization into a single workspace. This is where GitHub Projects becomes genuinely useful for teams managing multiple products or services in parallel.
Over 90% of Fortune 100 companies use GitHub (Kinsta, 2025). Most of them run organization-level projects, not repository-level ones.
Access Roles in Organization Projects
3 roles control what members can do inside a project:
- Read: view items, views, and fields, no editing
- Write: add items, edit field values, create views
- Admin: full access including deleting the project and managing member access
Role assignment happens at the project level, separate from repository permissions. A developer with Write access to a repo can have Read-only access to the project, and vice versa.
Internal vs. Public Project Visibility
Organization projects have 3 visibility options: private, internal (visible to all org members), and public (visible to anyone).
Internal visibility is the most practical default for most teams. All org members can see the roadmap without the project being indexed publicly. Public visibility works well for open source projects where external contributors need to see what’s planned and what’s already claimed.
Atlassian’s open source projects like those under the Apache Software Foundation use public project boards extensively for contributor coordination. GitHub’s own public repositories follow a similar pattern for community-facing software development process visibility.
Using Project Templates Across Teams
GitHub supports copying an existing project as a template for new ones. The copy preserves all custom fields, saved views, and workflow configurations, but not the items themselves.
For engineering organizations standardizing their software development methodologies across teams, a template project removes the setup overhead that causes inconsistency. One well-configured project becomes the starting point for every new product area or squad.
| Visibility | Who Can See It | Best For |
|---|---|---|
| Private | Only invited members | Unreleased products, internal roadmaps, confidential planning |
| Internal | All organization members | Cross-team collaboration, shared engineering visibility within an org |
| Public | Anyone on the internet | Open-source projects, contributor coordination, public roadmaps |
What Are the Keyboard Shortcuts and Productivity Features in GitHub Projects?
Keyboard shortcuts save roughly 5 minutes per day per developer, which adds up to around 30 hours per year (Konstantin Borimechkov, Medium). That’s not nothing across a 10-person team.
GitHub has over 80 keyboard shortcuts across the platform (UseTheKeyboard). The ones specific to Projects focus on navigation, item editing, and view switching.
Key Shortcuts for Daily Project Work
Command palette: Ctrl+K (Windows/Linux) or Cmd+K (Mac) opens the command palette from anywhere in the project.
From the command palette you can switch views, add new fields, trigger workflows, and navigate to specific items without touching the mouse. It’s the single most useful shortcut in GitHub Projects and the least used one.
?on any GitHub page opens the full shortcut reference for that pageSpaceopens a selected item in the side panelTabmoves focus between editable fields in Table viewEnterconfirms an inline edit
Bulk Editing and Inline Field Updates
In Table view, clicking a cell and pressing Tab moves directly to the next field without reopening the item. Whole rows of field values update without a single page load.
Bulk editing works by selecting multiple rows with the checkbox column, then using the field dropdowns that appear in the top action bar. Changing the Iteration or Assignee for 20 items at once takes about 5 seconds.
Teams using keyboard-first workflows in tools like Linear report 40% less context switching during sprint planning sessions compared to click-heavy tools (johal.in, 2024). The same principle applies to how GitHub Projects shortcuts reduce friction in daily standups and triage sessions.
Sharing Filtered Views with Teammates
Every saved view in GitHub Projects has a unique URL that preserves its filters, grouping, and sort order. Copy the URL from your browser and share it directly.
The person receiving the link sees exactly the same filtered view you do, assuming they have at least Read access to the project. No screenshots, no “go to Projects, then filter by…” instructions needed.
How Do GitHub Projects Compare to Jira, Linear, and Trello?
GitHub Projects, Jira, Linear, and Trello represent 4 different approaches to engineering project tracking. The right choice depends entirely on team size, process complexity, and how much of your workflow already lives in GitHub.
In the Stack Overflow Developer Survey 2024, Jira led async collaboration tools at 57.5% usage, while GitHub came in at 16.2%. That gap is real, but context matters: most teams using GitHub Issues + Projects are not reporting them separately as a project management tool.
| Tool | Best For | Weakness | Cost (approx.) |
|---|---|---|---|
| GitHub Projects | Teams already working in GitHub, small to mid-sized dev teams | Limited advanced reporting (e.g., velocity charts, deep analytics) | Free to ~$4/user/month |
| Jira | Large organizations with complex workflows and dependencies | Heavy interface, steep learning curve, context switching overhead | ~$7–$14.50/user/month |
| Linear | Fast-moving product and engineering teams | Less flexible for non-engineering or cross-functional workflows | ~$9/user/month |
| Trello | Simple kanban boards and non-technical teams | No native code integration or iteration planning features | Free to ~$5/user/month |
GitHub Projects vs. Jira
Jira handles projects with 100,000+ issues and supports fine-grained workflow enforcement, velocity charts, and JQL query reporting. GitHub Projects does not match that depth (IdeaPlan, 2026).
The trade-off is context switching. Developers work in GitHub but track work in Jira, which creates constant friction even with integrations. A 2024 case study across 12 engineering teams found that migrating from Jira to GitHub Projects and Linear cut sprint planning time by 25% and reduced context switching by 40% (johal.in).
Jira is the right call for organizations that need compliance-level workflow enforcement, portfolio reporting, or continuous integration pipelines tied to structured approval gates. GitHub Projects is the right call when the team already lives in GitHub and a separate tool creates more overhead than it solves.
GitHub Projects vs. Linear
Linear scored 4.6/5 for user experience vs. Jira’s 3.2/5 in a 2024 developer satisfaction survey, but scored lower for enterprise capabilities (onehorizon.ai). GitHub Projects sits somewhere between the two on both dimensions.
Linear’s main advantage over GitHub Projects is speed and cycle time analytics. Its main disadvantage is cost: Linear Pro runs $9/user/month, while GitHub Projects is included free with any GitHub plan. For teams already paying for GitHub Teams at $4/user/month, GitHub Projects is effectively zero additional cost.
GitHub Projects vs. Trello
Trello is simpler. That simplicity is also its ceiling.
Trello has no native connection to pull requests, commits, or continuous deployment pipelines. There is no way to close a Trello card when a PR merges. For any team that writes code on GitHub, that disconnection adds manual work every single sprint.
GitHub Projects replaces Trello entirely for development teams. Trello remains useful for non-technical teams managing content calendars, event planning, or marketing campaigns where code integration is irrelevant.
FAQ on How To Use GitHub Projects
What is GitHub Projects and how is it different from GitHub Issues?
GitHub Issues are individual work items: bugs, tasks, feature requests. GitHub Projects is the planning layer on top. It pulls issues and pull requests from one or more repositories into a single board with views, custom fields, and workflow automation.
Is GitHub Projects free to use?
Yes. GitHub Projects is included on the Free plan for individuals and public repositories. Organization-level projects with historical Insights charts require the GitHub Team plan at $4 per user per month or higher.
How do I add issues to a GitHub Project?
Open your project and click “+ Add item” at the bottom of any column or table row. Search for existing issues by title, add them in bulk from a repository’s issue list, or create draft items directly inside the project board.
What is the difference between Board view, Table view, and Roadmap view?
Board view is a kanban-style layout for sprint tracking. Table view is a spreadsheet for bulk editing and backlog management. Roadmap view displays items on a timeline, best for release planning and milestone tracking across iterations.
How do I set up sprint planning in GitHub Projects?
Create an Iteration field in your project settings. Set a start date and iteration length (one or two weeks is standard). GitHub generates sprints automatically from that cadence, and you assign issues to each iteration from Table or Board view.
Can GitHub Projects automate status updates?
Yes. Five built-in workflow triggers handle the most common updates: item closed, item reopened, pull request merged, code changes requested, and item added to the project. Enable them from the Workflows menu in project settings with no code required.
How do I track project progress in GitHub Projects?
Use the Insights tab to view current and historical charts built from your project data. The default burn-up chart shows completed vs. remaining work over time. You can filter charts by iteration, assignee, or label and configure the Y-axis to display story points.
What custom fields can I add to GitHub Projects?
GitHub Projects supports six field types: Text, Number, Date, Single select, Iteration, and Tracked by. Single select fields work well for priority levels. Number fields work for story points. All custom fields appear across Board, Table, and Roadmap views automatically.
How does GitHub Projects compare to Jira?
Jira has deeper workflow enforcement, velocity charts, and cross-project reporting. GitHub Projects keeps everything inside your existing GitHub workflow with zero context switching. Teams under 30 developers rarely need Jira’s added complexity, and GitHub Projects is significantly cheaper.
Can I use GitHub Projects across multiple repositories?
Yes. Organization-level projects pull issues and pull requests from every repository inside the organization into one workspace. Use the filter syntax repo:org/repo-name to scope any view to a single repository when needed.
Conclusion
This conclusion is for an article presenting how to use GitHub Projects as a complete issue tracking and backlog management system built directly into your existing workflow.
You now know how to configure custom fields, set up iteration fields for sprint cycles, and use workflow automation to keep status updates accurate without manual effort.
The Roadmap view handles release planning. The Insights tab covers burn-up tracking. Organization-level projects connect multiple repositories into one workspace.
None of that requires a separate tool or an extra subscription. ProjectsV2 gives most development teams everything they need for solid agile project management at the team collaboration level they actually operate at.
Start with one project, one board, one sprint. Build from there.
- How to Rename a Branch in GitHub Without Breaking Things - September 16, 2026
- Can Your Infrastructure Handle High-Volume Traffic? Understanding 10Gbps Servers - September 16, 2026
- What email HTML teaches frontend developers: tables, inline CSS, and client quirks - September 15, 2026
