GitHub Projects & Issues: A Primer

Owned by Sarina Canelake
Last updated: Apr 26, 2023 by Ned Batchelder (Deactivated)
3 min read

Working with GitHub Issues

An “Issue” is similar to a “ticket” (Jira) or “card” (Trello). Issues are made within a repository (often, your working group’s repository) and can be made by anyone, no specific access required. To begin, navigate to your repository, click the “Issues” tab at the top, and then click the green “New Issue” button:

Next, across from “Blank Issue” click the green “Get started” button to open a new ticket without a template (if your project wants templates, we can provide them!):

Finally, you can type a title and body into the ticket, and click “Submit new issue” to make a ticket.

KNOWN ISSUES:

  1. You can mention any user you wish on a ticket using “@” followed by a GitHub username (for example, @sarina). However, auto-complete will only work for users who’ve been added to the repository.

    1. Unfortunately, we are at a user limit and cannot add more people to the GitHub organization

    2. You will need to copy-paste usernames, or enter them from memory, after the “@” symbol. They will get notified!

  2. To prevent spam, GitHub does not allow you to assign anyone to a ticket unless they’ve already commented on the ticket.

    1. Solution: Any user can write a comment that only says, assign me, and the ticket will be assigned to them.

    2. You can “@” mention the user and ask them to type this comment, as well.

  3. Only organization members can add/remove labels

    1. Solution: Any user can write a comment that only says, label: label name to add a new label to a ticket. All words after “label:” become the new label

    2. Solution: Any user can write a comment that only says, remove label: label name to remove a label from a ticket. All words after “remove label:” comprise the label to be removed. If the label is not on the ticket, nothing happens.

More Information

GitHub’s Issue Quickstart: https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart

Working with GitHub Projects

GitHub Projects are a lot like Jira or Trello boards. Learn more about projects here: https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects

A project board has a few types of views. One view is the “board view”, and you can have many such views based on different filters. To see what’s possible, checkout the Roadmap Board: https://github.com/orgs/openedx/projects/4

Projects can also have one or more table views. Check out the BTR board for examples of ways to use the table view. https://github.com/orgs/openedx/projects/28

If needed, you can automatically add issues to projects a few different ways. Details are at How to have issues and pull requests added to GitHub Projects.