This is a reference for using GitHub as a project management tool. I will be using GitHub's beta project which has slightly different functionality than the default project.
For those that have used other project management tooling, issues are akin to JIRA stories or trello cards. Per GitHub's own definition: Use GitHub Issues to track ideas, feedback, tasks, or bugs for work on GitHub. Think of an issue as the place to track work (e.g. development) that is happening within the project.
Issues are scoped to a repository. Knowing this will help you figure out which of the following paths will be most convenient for managing them.
You can easily create an issue right from the repository itself. You can either click the Issues tab while viewing the repository or go to url: https://github.com/{user}/{repo-name}/issues (swapping the relevant fields to your repo). There is a handy New Issue button.
Keyboard shortcut
G+Iwill open up the issues tab Once in the issues list view,Cto create new orCmd+K|Ctrl+Kto open up command palette. Select the repo and type issues to go to the issues list view.Check out other handy shortcuts for Issues
Another way to create issues is by building and leveraging templates. This is helpful for specifying a structure and what kinds of information are required to be added to the issue. You can even specify different templates for bugs, feature, or create your own custom set.
I recommend creating issues from scratch first to get the feel as a group/team for what kinds of information is helpful and relevant before jumping into template off the bat. This is an optimization tool.
Depending upon which workflow you are trying to optimize for (e.g. maintainers, consumers), you can also look at using issue forms which is a more guided approach to creating issues.
From your project, adding an issue is as easy as clicking the + which will then prompt you to Type to add a draft issue or use # to search. Searching allows you to specify the repo and then find your issue.
Drafts allow you to quickly type out the idea, hit enter and continue adding more ideas to the board. You can click on the draft itself (when hovering you will see it is a link). When opening up the draft you will see that it has a title, description, assignee, status, and all the custom metadata fields (will cover later) added to the board.
The difference with the draft issue state and a full blown issue is:
- Draft only exists on the board and is not yet attached to the repository. This will only be true if your project is at the organization level and not directly attached to a repo (will cover later why this is useful)
- Notifications will not go out to assignees
When you are ready to convert to an issue, you have links to do to in either the preview mode or by clicking the drop-down to the left of the draft title on the project board.
This will cover interesting things you can do within Issue content and associated metadata for an issue.
Sometimes you will have a beefy issue where you want to break up the work into smaller chunks. Issues support task lists which is similar to the idea of sub-tasks in JIRA.
Within a task list, you can reference other issues. This can be done by adding the issue # (if within the same repo) or with syntax user/repo#[issue-number].
- #1000
- etsy/knowledge-base#10
Doing this unlocks some interesting effects:
- When an issue is added to a task list, it will show "tracked in [issue #]" at the top with a handy link so you can quickly view the parent.
- When the referenced issue is closed, the task item is automatically marked as completed. This also updates the task progress information at the top of the parent issue (e.g. 2/3 tasks completed).
If an issue tracks the general work being done, pull requests are a call for feedback to have other fellow maintainers and/or team members review changes to the repository that are about to be committed into the main branch. PRs are incredibly helpful to communicate upcoming features, architecture changes, and anything else that fellow maintainers should inspect to maintain quality.
There is a lot to explore with PRs but in this case we will focus on linking them to issues.
Linking a PR to an issue is through a couple different options:
- Within an issue, the right-hand side allows you to add linked pull requests. Click the gear and search for the PR. Search box will filter to the PRs within the same repository.
- Within a PR, the right-hand side allows you to add linked issues. Click the gear and search for the issue. Search box will filter to the issues within the same repository.
- Within a PR, you can add special keywords in the description or commit message that will specify that the issue will be resolved/closed/fixed by this PR.
Word of caution for option 3. If you will have multiple PRs, make sure to think through which PR will be the last one to truly close out the issue. That will avoid some headaches with the issue being closed prematurely with multiple PRs linked.
Milestones allow us to group related issues together. This can be similar to the Epic concept in JIRA. With a Milestone you can view its progress which is just a reflection of open vs closed linked issues.
Similar to issues, milestones are also scoped to a repository. To view the list of milestones you actually need to go to the Issues list. Next to the New Issue action in the top right, you will see a Milestones quicklink. Within this view, you can create milestones and also create issues directly within a milestone (surprise! another way to create issues).
To link a milestone to an issue, you have the following options:
- Within an issue, the right-hand side allows you to add milestones. Click the gear and search for the milestone. The search is pretty picky and expects you to enter contiguous phrases. Search box will filter to the Milestones within the same repository.
- Within your project, you can easily specify the milestone field. Since the milestone is attached to an issue (each row in the table view), the search box will filter the results to the same repository as the issue.
Note: At the time of this writeup, GitHub issues do not support a
cancelstate. The issue is either open or closed. With that said, if you did in fact mean to cancel an issue (maybe it was a duplicate or no longer needed), you should remove the issue from the milestone to not inflate milestone progress.
Like PRs and milestones above, you can link an issue to a project. This is extremely helpful to track the lifecycle of an issue (beyond just open and closed states). Attaching it to a project also gives visibility to the team whether this is work that is being proposed, planned, prioritized, is in progress, in testing, and anything else that may apply.
Linking an issue to a project can be done a couple of ways:
- Within an issue, the right-hand side allows you to add project(s). Click the gear and search for the project. You can filter by repository or organization depending on where your project was created. Once you link the project, you can specify the appropriate status.
- Within the project, you can add issues using the
+or typing#.
Worth checking out best practices for managing projects.
I found it helpful to think about a beta project like a spreadsheet where each tab is just a different view of the same data. As a team is working through the backlog and figuring out which work to prioritize vs reviewing status of work currently in flight, you could see how each of those can be different views of the same overall list of work.
Each tab within the project is a view. Within a view you can specify whether you prefer to see the data in a table or board view, show/hide fields, change order of the fields, specify sort order, and filters.
When you make changes to the view, you will notice a blue circle by the tab drop-down. This is a signal that you have made changes and should save if you want those to persist (and for other team members to see the same view!).
You can create custom fields for issues that make the project board even more relevant to team processes, discussions, and workflow. You can also view these custom fields right from the issue itself. To do so, open up the issue. On the right-hand side you will see the linked project. There will be a link within its boxed area which will say something like +[#]more. When you click the link you will see all the custom fields for this issue and its values.
Because all the data is shared within the project, you can reuse custom metadata fields across views.
GitHub supports some basic workflow configurations out of the box. This helps the team streamline issue and PR lifecycle across the project. For example, when an issue and/or PR is closed, you can specify that you automatically want the status to be mapped to done.
The following is a list of functionality that currently is not supported and would help simplify project management within GitHub.
-
Issues don't support distinguishing between close states: work is completed and canceled/no longer needed or relevant
-
Project board view does not support group by. This would be similar to the JIRA swimlane functionality, allowing you to help break up while still leveraging the ease of use of a board.
-
Project view filters require there to be at least one issue that matches the criteria. This can be frustrating when you are adding a new data value to a single select field and want to exclude it from other views and forget to attach it to at least one issue.
-
Project views don't support ignoring columns. This would be helpful to show different statuses based on specific views.
-
Filtering issues with no projects currently doesn't work for beta project. Issues linked to a non-beta project are currently being flagged as having a project.