Much like GitHub Organizations, Codetree Organizations represent a billing entity and its users. Codetree Projects represent a collection of one or more GitHub Repositories and their associated issues. An Oganization can have multiple Projects.

For example, if your company has two products, A and B, you would likely create a Project for A and a Project for B. These Projects would each have their own independent issues, permissions and workflows.

The relationship between Organizations, Projects and Repositories

It’s common for the code that makes up a single product or service to live in different GitHub Repositories (for example, a single product could have code live in three different repos: an API repo, a mobile app repo, and a front end repo). In Codetree, Projects provide a way to unify issues from related GitHub Repositories. Once multiple Repositories are part of the same Project, their issues are displayed and managed together in much the same way as if all of the issues were in a single Repository. There are a number of reasons why you might want to manage issues in different repositories in a unified way. Some examples include:

In fact, the same Repository can live in multiple Projects. When a Repository is in multiple Projects its issues will show up in and be editable in each Project simultaneously.

Once a group of Repositories are part of a Project, Codetree will:

When a Repository is first added to a Project, Codetree will automatically add each Label and Milestone that exists in the newly-added Repository to all the other Repositories that are also part of the Project.

Similarly, each Label and Milestone that are in the other Repositories that are already part of the Project will get added to the newly added Repository.

If, at a later date, you add, delete or rename a Label or Milestone, Codetree will ensure that all of the corresponding Labels and Milestones in all Repositories that are part of the Project will also end up with the same change applied. This is true whether the Milestone or Label was created in GitHub or in Codetree.

Adding a Label in Repo A adds a Label with the same name to Repo B because they are part of the same Project.

Codetree support two different ways of viewing and managing Issues:

In Codetree both Lists and Boards are always driven by filters. In effect you have one centralized set of all Issues from all Repositories in your Project and you can view slices of those Issues by filtering. The base case is the filter for “all Issues". When looking at a filtered set of Issues you can choose to display those Issues in either a List or a Board view.

List view provides an information dense way of working with Issues. Because Lists are information dense they are particularly useful for project management tasks like triage. Board view is great for individual developers doing Kanban or Scrum style workflows or for managing an individual milestone. This is because you can visualize where each issue is in the overall workflow. Both Lists and Boards allow you to prioritize Issues in stack rank order via drag and drop.

The same issues can be displayed in either List view or Board view.

GitHub Issues have two states: Open and Closed. On top of GitHub’s Open and Closed states, Codetree adds the concept of Stages. Stages work in conjunction with GitHub’s Open and Closed states to allow you to define a custom workflow that matches how your team works. Codetree has a set of built-in Stages. You can also add your own custom Stages. Codetree automatically stores Stage information in GitHub Labels so you can still set and filter using Stages from inside GitHub.

Stages map to columns in Board View. Dragging an Issue from one column to another in Board view moves an issue to that Stage. You can also move an Issue to a stage in List view via the Edit Issue Dialog.

Codetree has three built in stages:

By adding custom Stages you can create a workflow that maps to how your team works. You can add custom Stages from the Project settings screen. For example, if your team's process requires Issues to be submitted for code review and then go for user acceptance testing before being closed you would create custom Stages for “Code Review” and “UAT” like this:

After adding custom Stages your Boards include a Code Review and UAT columns.

When managing your project you’ll likely have a set of filters that you use on regular basis. For example, "show me all of the blocked issues” or “show me all of the UI polish issues”. Codetree calls these Shortcuts. Codetree has a set of useful out-of-the-box Shortcuts. Shortcuts show up in the left-hand navigation.

You can also create your own Shortcuts which will be added to the left navigation just like the out-of-the-box Shortcuts. When you save a Shortcut you can choose to make it available to all users that are part of the Project or only available for yourself.

You can manage Saved Shortcuts via the projects settings screen.

If you’d like to track sizing information for Issues in Codetree you can enable the Points feature from the Project settings screen. You can add Points to issues in either List or Board view and Codetree will automatically rollup the total points for your Milestone.

Learn more about using points here.

Codetree has three different permission levels or roles:

Owners and Admins are Organization-level roles and have full access to all Codetree Projects that are part of the Organization. Owners have access to billing information while Admins do not. Owners and Admins are configured using the Members tab in Organization settings.

Collaborators are tied to individual projects and have full access to issue data that is part of the Project. Regardless of your permission level in Codetree, if you do not have access to the Issue data in GitHub you won’t be able to access the Issues in Codetree. Collaborator access is configured using the Project permissions screen.