13 Creating and using GitHub Issues
13.1 Learning objectives
The learning objectives of this session are:
- Use GitHub Issues to start discussions, request help, list to-do tasks, or comment on existing “issues”.
- Explain the benefits of using issues to keep track of discussions and to-do lists within the same platform as your files.
In this session, we will not add files to or edit files in the repository. Instead, we will focus on creating and using GitHub Issues to keep track of tasks and discussions in your project.
13.2 📖 Reading task: What are GitHub Issues?
After the reading task, emphasise that issues are not files in the repository, but a separate tool for keeping track of tasks and discussions.
Time: ~7 minutes.
So far, we’ve covered how to create repositories, add files, and make changes to files. But what if you want to keep track of tasks or ideas for future work, or you need to discuss something with your collaborators before you add it to your repository? This is where GitHub Issues come in.
GitHub Issues are “items” or “records” that can help you keep track of to-do tasks and discussions related to a specific project (as a repository). Issues are not files in your repository; they are completely separate from the repository’s files and folders which we have been working with so far in the “Code” tab on GitHub. Instead, issues live in the “Issues” tab in your repository on GitHub. Later in this session, we’ll create multiple issues, so you don’t have to go to this tab right now. For now, it’s enough to know that issues aren’t files in your repository, but a separate tool for keeping track of tasks and ideas.
Issues can be used in many ways. For example, you can use them to:
- Keep track of tasks you need to do.
- Discuss ideas with your collaborators.
- Report problems, bugs, or mistakes.
- Plan future work.
- Ask questions or request help from collaborators.
Issues can be assigned to specific people. By assigning an issue to someone, it becomes clear who is responsible for completing the task referenced in the issue. Another useful feature is that you can tag people in comments to notify them of the task or discussion. You tag people by typing @ followed by the person’s username. Depending on the person’s notification settings, they will receive an email and/or a notification on GitHub when they get tagged.
Once you have created an issue, you can add comments to it, discuss the task with your collaborators, and close the issue once the task is completed. This way, you can keep track of what needs to be done and what has already been completed.
You can also assign issues to yourself or others to keep track of who is responsible for completing the task. This is especially useful in collaborative projects where multiple people are working on the same repository. By assigning issues, you can ensure that everyone knows who is responsible for what task. You can assign people by going to the “Assignees” section on the right side of the issue page and clicking on the person’s username. If you want to assign the issue to yourself, you can click on your own username in the “Assignees” section.
Anyone with access to the repository can create an issue. This means that you can create issues in your own repository and in public repositories in general. This can be very useful if you, for instance, want to suggest a change or report a problem in another person’s repository.
All issues in the repository are available in the “Issues” tab, where you can see a list of all the issues in the repository. You can also filter the issues by their status, such as “open” or “closed”, and by who they are assigned to. By default, only open issues are shown.
Now that you’ve read about what GitHub Issues are, let’s practice creating issues in the repository.
13.3 Creating a GitHub Issue
Since we’ve decided that our recipe book should only include recipes for sweets and baked goods, we might want to add a sweets recipe, like chocolate-covered strawberries or chocolate mousse, in a sweets/ folder. Let’s create an issue to keep track of this task.
In the repository, we’ll click on the “Issues” tab. On this page, we’ll see a list of the open issues in our repository. Since we (or someone else) haven’t added an issue yet, this list is empty. We will create a new issue by clicking the “New issue” button in the top-right side of the page. We can see two fields for the issue: A title and a description. The title is a short summary of the task we want to complete, while the description provides more details about the task. Let’s give the issue the title “Add chocolate mousse recipe” and write that we want to add a chocolate mousse recipe in a new sweets/ folder in the description box.
Since this is a very simple task, the description doesn’t add much new information, but it’s good practice to write a description that explains the task in more detail.
We can also assign someone to the issue so it is visible that they are responsible for completing this task. Let’s assign it to ourselves. We do this by going to the “Assignees” section on the right side of the page and clicking on our username.
Finally, let’s click the “Create issue” button in the bottom right side of the page to create the issue.
Once we’ve created the issue, when we click the “Issues” tab we’ll see the new issue in the list of the repository’s issues. We can see the title of the issue, when it was made and who opened the issue. We can also see a number with a # in front of it. This is the number of the issue, something that GitHub creates automatically. We can use this number to refer to the issue in comments or discussions, also in other issues in the same repository. When we click on the issue, we can see more details, such as comments, and we can also close the issue once the task is completed.
We have now created our first issue 🎉!
If you want to see an overview of the issues in a specific repository, you can go to the “Issues” tab in that repository.
But if you want to see all the issues you have created across repositories, you can click the “Your issues” button in the top-right corner of the GitHub page. It looks like 
.
When you click that, you’ll see a list with all the issues you have created across all repositories. Nice! ✨
13.4 🧑💻 Exercise: Create an issue to discuss future recipes
Time: ~10 minutes
Imagine that you would like to discuss or brainstorm some ideas on what recipes to add to your recipe book next. Since GitHub Issues can be used for exactly that purpose, it makes sense to create one to keep track of these ideas:
In your repository, click the “Issues” tab, and then the “New issue” button.
Fill in the title with text like “What recipes to add next?”. Then fill in the description box with some recipes you might want to add in the future. If you don’t know any recipes or are not sure, you could write something like:
In the future I want to add more recipes to this project, but I'm not entirely sure what to add yet. I'm open to suggestions! Maybe, it could be: - Carrot cake - Chocolate-covered strawberries - Apple pieTo inform the person you would like to get suggestions from, you can tag them in the issue. To do this, type
@followed by the username of the person you want to tag. For example, if you want to tag someone with the user namesignekb, you would type@signekb. Ask your neighbour to give you their GitHub username and tag them in the issue. You could write: “Hey @[neighbour’s GitHub username], what do you think about the recipes I’ve listed here? Do you have any other suggestions?”When you have added a title and description to the issue as well as tagged your neighbour in it, click the “Create” button to create it.
You now have an issue to remind yourself of recipes you want to add! 🍰
13.5 GitHub notifications
Before going through the inbox section, it can be helpful to get someone to mention you in an issue so you can show how the notifications works. Slowly walkthrough the inbox section, as it can be a lot to take in at once.
Now that you’ve been tagged in your neighbour’s issue, you will have received a notification on GitHub (and probably also an email).
To see the notification, we’ll click on the notification button with the inbox icon in the top right corner of the GitHub page that looks like 
. This will show a list of your notifications, including the one from your neighbour’s issue.
Let’s take a moment to look at the information in this notification. We can see the title of the issue, who created it, and the repository it’s in. We can also see that we’ve been mentioned in this issue.
If we click on the notification, it will take us to the issue page. Here we can see the issue with all its details.
Since you’ve been tagged in your neighbour’s issue, you should be able to find the issue fairly quickly. You can go to the notifications by clicking the inbox button in the top right corner on GitHub () and click on the issue to see the details.
However, if you haven’t been tagged, you can’t find the issue this way. So, let’s practice finding the issue in your neighbour’s repository.
13.6 👩💻 Exercise: Comment on your neighbour’s issue with a recipe suggestion
Time: ~10 minutes
One of the great things about GitHub is that it makes it easier to collaborate with others. So, interact with someone else’s issue by adding a comment to it. With your neighbour one at a time:
- Go to your neighbour’s GitHub repository by typing their username (for example,
signekb) into the search bar at the top. If you seerepo:in the search, delete it since this will search for repositories with that name. Press Enter. Then click on the “Users” tab in the left sidebar to find their profile. Click their username to open their profile page, then go to the “Repositories” tab and open the repository they created for this workshop. - Go to the “Issues” tab in their repository.
- Click on the issue that they have created with the list of future recipes.
- Scroll down to the bottom of the page and write a comment in the comment field suggesting a recipe that they could add to their recipe book. For example, you could suggest that they add a brownie recipe as well 🍰.
- When you have written your comment, click the green “Comment” button to post the comment.
If you want to edit your issue or your comment to an issue, you can do so by clicking the 
button on the right side of the issue or comment. This will open a dropdown menu. Click “Edit” in the dropdown. From here you can change the title, description, or comment text.
Once you have made your changes, click the “Save” button for issues or “Update comment” for comments to save the changes.
13.7 💬 Discussion activity: Consider the advantages of issues in your own work
Time: ~4 minutes.
To connect what we’ve learned to your own daily work, consider what advantages (and barriers) there are to using issues in your own work.
- Take ~1 minute to think how you would integrate issues into your work and what advantages and challenges there may be.
- Pair up with your neighbour, and take 1.5 minutes each to share what you’ve thought about.
13.8 Summary
In this session, we have learned about GitHub Issues. Specifically, we have:
- Created our first issues: One to keep track of a future task (adding the a chocolate mousse recipe in a new
sweets/folder) and one to start brainstorming ideas on which recipes to add in the future. - Explored GitHub notifications.
- Navigated Github to find other people’s repositories and issues.
- Started to collaborate a bit by commenting on someone else’s issue to suggest a recipe.