14 Creating and using GitHub Issues
14.1 Learning objectives
The learning objectives of this session are:
- Use GitHub Issues e.g., to start discussions, request help, or list to-do tasks.
- Comment on existing issues.
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.
14.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: ~5 minutes.
So far, we’ve covered how to create repositories and work with files on GitHub. But as we’ve mentioned, GitHub can do more than version control. When working on a project, it’s common to have a list of tasks that need to be completed, ideas to discuss, or problems to solve. Keeping track of these things can be challenging, especially when working with others. This is where GitHub Issues come in.
Issues are separate from your repository’s files and folders in the “Code” tab; instead, they live in the “Issues” tab.
You can use issues to:
- Track tasks
- Discuss ideas
- Report problems or mistakes
- Ask questions or request help from collaborators
Issues can be assigned to specific people, making it clear who is responsible for what. You can also tag collaborators in issues by typing @ followed by their username, which notifies them by email or GitHub, depending on their settings.
Issues can be collaborative: you can add comments and reactions and close them once the task or discussion is resolved, making it easy to see what’s pending and what’s done.
Anyone with repository access can create issues which means that you can create issues in any public repository. This is useful if you want to suggest improvements or report problems in someone else’s project.
All issues related to a repository can be found in the “Issues” tab, where you can filter them by status (open or closed) and assignee. By default, only open issues are shown.
Now that you know what GitHub Issues are, let’s practice creating some in a repository.
14.3 Creating a GitHub Issue
Let’s imagine that we want to add a sweets recipe, like chocolate-covered strawberries or chocolate mousse, in a sweets/ folder of our recipe repository. 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. If we wanted to assign it to someone else, we would search for their username and click on it to assign them.
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! ✨
14.4 🧑💻 Exercise: Create an issue to discuss future recipes
Time: ~5 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! 🍰
14.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.
14.6 👩💻 Exercise: Comment on your neighbour’s issue with a recipe suggestion
Time: ~5 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.
14.7 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.