The Important Differences between GitHub Projects and Codetree

You may have seen that GitHub launched a feature called "Projects" at their recent conference, GitHub Universe. On the surface Projects appears to be a Kanban board that lets you manage your project. But if you dig a little deeper, GitHub Projects is different from Codetree's Kanban boards in several significant ways.

Click here if you want to skip to a table that summarizes the key differences between Codetree and GitHub Projects.

In this post I’m going to unpack GitHub Projects (GHP going forward) and cover four things:

  1. What is a GitHub Project?

  2. How do Projects work?

  3. What can I use them for?

  4. How is Codetree different?

1. What is a GitHub Project?

GHP lets you create multiple Kanban-style boards within a repository. Each board can have custom stages. It’s a very lightweight Kanban tool, like GitHub Issues is a lightweight issue tracking tool. It is very Trello-esque: a card can be an issue or a note (more on notes below), and cards can be dragged and dropped from column-to-column.

2. How do GitHub Projects work?

They’re Kanban boards. We’ll cover how to create a board, and then talk about three wrinkles that you might not expect:

  1. Boards exist within repos

  2. Boards contain a subset of issues

  3. Issues can belong to multiple boards

Creating a project

There’s a new Tab in the GitHub UI called Projects:

New Projects tab in GitHub UI

When you create a Project, you first define the stages in that project.

Customize your GitHub Project workflow

Boards can have different stages from other boards in the same repo.

Boards exists within a repo

A GHP lives within a repo. Which means you can only add issues from a repo to a board that lives in the same repo.

In other words, if you need to see a rolled-up view of issues across multiple repos, GitHub Projects won’t work for you.

Boards contain both notes and a subset of issues

You can create as many Kanban boards as you want within a repo. Each board contains a combination of a subset of issues in the repo, and a new construct called a "note". We'll cover both.

Adding an Issue to a Project

Issues need to be manually added to a project - a GHP has no issues when you create it.

Add issue to GitHub Project

If you’re trying to use a board to manage your entire project, you’ll probably be frustrated at having to add every issue to your board manually.

Adding a Note to a Project

GHP introduces the concept of "notes". Notes are simply plaintext snippets that you add to a board. They can be easily converted to a full-fledged Issue.

Add Notes to GitHub Project

Issues can belong to multiple boards

An issue can belong to multiple boards at once. You can see what stage and board(s) an issue belongs to on the Issue page:

View project and stage on an issue

3. What can I use GitHub Projects for?

There are three obvious ways to use GitHub Projects (and plenty of non-obvious ones, I’m sure!)

  1. As a proxy for Epics

  2. To track an assignee’s work

  3. To track issues within a milestone (e.g. a Sprint)

GitHub Projects as a proxy for Epics

GHPs are simply a way to group together a set of related issues and to visualize them. One way you may want to group issues together is if those issues are children of a larger feature. You can use a board to track the N features that need to be finished to deliver some larger feature.

Tracking an assignee’s work

You could create a board for each developer on your team and track their work as it gets delivered.

Track issues within a milestone

You could create a board for each milestone and see the work remaining before closing that milestone, what stage it’s in, and who it’s assigned to.

4. How are Codetree’s Kanban boards different from GitHub Projects?

There are several differences between Codetree and GitHub Projects that may be important to you.

Multiple repos

First, Codetree will show you all your issues from as many repos as you want rolled up into a single Kanban board. GitHub Projects can only show you a Kanban board that contains a subset of issues from a single repo.

Define your Kanban workflow once

In Codetree, you define your workflow once. All issues go through that workflow. In GitHub Projects, you need to define the columns on your board for every board you create.

See all your issues, automatically

Codetree’s Kanban board will automatically show you all your issues from your repos. You don’t need to add issues to your board - you can see them all.

With GitHub Projects you need to manually add issues to a board.

Filter your issues

Codetree lets you filter your board by multiple criteria to see the issues you want to see. Filter by milestone, assignee, and a whole lot more. You can combine your filters too - "Show me issues assigned to Joe for the Oct milestone with the ‘UX’ label". You can save your filters for quick access later.

GitHub Projects doesn’t offer any of this.

image alt text


Here are the key differences between Codetree and GitHub Projects.

TaskCodetreeGitHub Projects
Multiple Repo Support Shows all your issues from multiple repos in one view Shows subset of issues from single repo
Defining your Kanban Workflow Smart default. Just need to do it once No default. Need to do it for every board you create
Adding issues to a board All issues added automatically Need to add every issue manually
Filtering your issues on a board Filter by milestone, assignee, labels, creator, and more. No filtering
Combining filters Combine as many filters as you want, e.g. "Show me issues assigned to Joe for the Oct milestone with the ‘UX’ label" No filtering
Save shortcuts to filtered boards As many as you want - your filtered boards are a click away after you save the shortcut. No filtering or shortcuts

Use Codetree to Manage your entire project

If you want to:

  • Define your Kanban workflow once…

  • And automatically see all your issues in a single Kanban board…

  • Across the repos you choose…

  • While being able to filter them down to the issues you want to see…

  • And saving shortcuts to those views…

Then Codetree may be a better fit for you than GitHub Projects.

You can try Codetree out for free for 14 days here.