GitHub Projects (Beta): agile project management

Updated March 2026 11 min read intermediate

GitHub Projects is a flexible tool for agile planning and tracking. Create Kanban boards, automate workflows, gain insights, and manage your team's work – all integrated with your issues and pull requests.

What is a GitHub Project Board?

📋 Todo

Issues to start

⚙️ In Progress

Active work

✅ Done

Completed tasks

Visualize your workflow, drag-and-drop cards, and track progress in real-time.

Step 1: Create your first project

There are two ways to create a project:

From your repository: Go to the "Projects" tab → Click "New project"
From your organization/user: Click the "Projects" section in your profile → "New project"

github.com/username/repo/projects → New project

Choose a template:

Table view – spreadsheet-like layout with fields
Board view – Kanban board with columns
Roadmap – Timeline view for planning

Pro tip: Start with "Board view" for agile workflows. You can always switch between views later!

Step 2: Add issues and pull requests

Projects are designed to track issues and PRs. Add them in multiple ways:

Drag and drop: Drag existing issues from the sidebar into your project board
Add from issue: On any issue, click "Projects" in the right sidebar and select your project
Use the "Add item" button: Click "Add item" at the bottom of a column, type the issue # or title

Try it: Click the "+ Add item" field, type "#42" or paste an issue URL. Press Enter to add.

You can also add draft issues – placeholder cards that aren't tied to an actual issue yet. Great for brainstorming!

Step 3: Customize columns and fields

Make your board fit your team's workflow.

Adding/renaming columns (Board view):

Click the "..." menu on any column → "Edit column"
Add new columns with the "+" button at the end
Rename default columns: Todo, In Progress, Done
Common custom columns: "Review", "Testing", "Blocked"

Custom fields (Table view):

Click "⚙️" (Settings) → "Fields" → "New field"
Field types: Text, Number, Date, Single select, Iteration
Add fields like "Priority", "Story points", "Sprint", "Assignee"

Custom fields power your insights! Use fields to filter, sort, and create charts.

Step 4: Automation – let GitHub move cards for you

Automation rules save time by automatically moving items when certain events happen.

Built-in automation (Board view):

Click the "..." menu on a column → "Automation" to enable:

Todo column: New issues automatically added to Todo
In Progress column: When someone is assigned → move to In Progress
Done column: When an issue is closed → move to Done
Reopen: If issue is reopened → move back to Todo/In Progress

Advanced automation with GitHub Actions:

name: Auto-move to In Progress on assign

on:

  issues:

    types: [assigned]

jobs:

  move-card:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/add-to-project@v1.0.0

Automation keeps your board up-to-date without manual dragging. Perfect for teams!

Step 5: Switch between views

GitHub Projects offers multiple ways to visualize your work. All views are linked – changes in one reflect everywhere.

Table View

Spreadsheet layout with all fields, filters, and sorting

Board View

Kanban columns based on a field (e.g., Status)

Roadmap

Timeline view for planning milestones and dates

To switch views: Click the view selector at the top of your project (Table, Board, Roadmap, or custom views).

Save custom views: Apply filters/sorting, then click "Save view" to reuse later.

Step 6: Insights – measure what matters

The "Insights" tab gives you powerful charts and metrics about your project.

Available charts:

Burndown chart: See progress toward completion over time
Velocity: Track how much work your team completes per iteration
Cycle time: Measure time from "In Progress" to "Done"
Distribution charts: Visualize by assignee, label, priority, etc.

Insights example:
Shows that your team completed 12 issues last week, average cycle time is 3 days, and 85% of items are on track.

Use insights for sprint retrospectives, team planning, and stakeholder reports.

Step 7: Powerful filters

Filter your project to focus on specific items.

status:"In Progress" label:bug assignee:@me

Common filters:

status:Todo – items in Todo column
assignee:@me – items assigned to you
label:bug – items with bug label
milestone:v2.0 – items in a specific milestone
no:assignee – unassigned items
is:issue is:open – open issues only

Combine with AND/OR and parentheses for complex queries.

Project management best practices:
✅ Define clear columns that match your workflow
✅ Enable automation to reduce manual updates
✅ Use custom fields for priority, story points, sprints
✅ Review insights weekly to improve processes
✅ Create multiple views for different stakeholders

GitHub Projects FAQ

What's the difference between Projects (classic) and Projects (beta)?

Projects (beta) is the new version with more features: multiple views (table, board, roadmap), custom fields, better insights, and improved automation. Projects (classic) is being phased out.

Can I have multiple projects for one repository?

Yes! You can create as many projects as you need. For example: a sprint board, a roadmap project, and a backlog grooming project.

How do I add items from multiple repositories to one project?

Create the project at the organization or user level (not inside a single repo). Then you can add issues and PRs from any repository you have access to.

Can I automate moving cards based on labels or assignees?

Yes! Use the built-in column automation for simple moves, or GitHub Actions for advanced logic (e.g., move to "Review" when label "needs-review" is added).

What are "draft issues" in projects?

Draft issues are placeholder cards not linked to a real issue. Perfect for brainstorming, ideas, or tasks that don't need an issue yet. They can be converted to real issues later.

How do I use iterations/sprints in Projects?

Create an "Iteration" custom field. Add time periods (e.g., Sprint 1: Mar 1-14). Then you can filter by sprint and view progress in the Roadmap view.

Can I export data from Projects for reporting?

Yes! Use the "Export" button in the Table view to download as CSV. You can also use the GitHub API to programmatically access project data.

What's the difference between a project and a milestone?

Milestones group issues by a specific goal or release. Projects track workflow status across multiple milestones and can include non-issue items.

Can I assign story points or priority values?

Yes! Add a custom field of type "Number" for story points, or "Single select" for priority (High/Medium/Low). Then you can sort, filter, and create charts based on these fields.

How do I share my project with stakeholders?

Project visibility follows your repository/organization settings. For public repos, projects are public. Share the project URL, or use the "Insights" tab to create charts you can share in presentations.

Can I use Projects for personal task management?

Absolutely! Create a project in your personal account. Add issues from any repositories you own or contribute to, plus draft items for personal tasks.

Is there a limit on how many items a project can have?

No hard limit, but very large projects may load slower. For best performance, consider archiving old completed items or creating new projects for each quarter/sprint.

Previous: Issues & labels Next: GitHub Actions

GitHub Projects transforms how teams plan, track, and deliver work. Start organizing your next project today!