GitHub for Beginners: Getting started with GitHub Issues and Projects

Welcome back to GitHub for Beginners, our series designed to help you navigate GitHub like a pro and get the most out of it! We’re bringing you a double dose by sharing these episodes in video format and adding them to our blog, so you can consume the material in whichever form works better for you!

We’re now entering our third season! In the previous seasons, we focused on a general introduction to all things Git and then spent an entire season talking about Copilot. This season, we’re going back to the basics and exploring the core features of GitHub. Our goal is to help you level up—or dust off—your GitHub skills.

In this episode, we’re going to start with two of GitHub’s most powerful collaboration tools: GitHub Issues and Projects. By the end of this post, you’ll know how to create an issue, how to sync your issues to a GitHub Project board, and how to use GitHub Projects to track your work.

Let’s get into it! Or, watch the full video above!

Why issues and projects matter

GitHub Issues and Projects are essential tools for any team that wants to stay organized and collaborate efficiently. Issues help you track tasks, bugs, and ideas, all in a clear shared space—ensuring nothing slips through the cracks. Projects look at the bigger picture, letting you visualize, prioritize, and plan your work, turning individual issues into an actionable workflow that everyone can follow.

By combing issues and projects, you can coordinate work, communicate progress, and ensure that everyone’s aligned toward the same goal.

Creating your first GitHub Issue

GitHub Issues are a simple way to capture anything that needs attention in your project, whether that’s a new idea, a bug, or a task. Think of them as the building blocks of what you want to add to or update in your project. They help teams work collaboratively and stay organized, while making sure that every item is addressed.

So how do you create an issue? Here’s a sample repository where you can try this out for yourself by following these steps.

1. Navigate to gh.io/gfb-issues in your browser. 
2. At the top of the page, click the Issues tab. 
3. In the top-right of the window, click the green New issue button. 
4. A window will appear with a couple of boxes. First, give your issue a clear title by entering it in the box under “Add a title.” 
5. Provide a description for your issue in the “Add a description” box. Your description should include all of the relevant information necessary to set expectations. When someone attempts to resolve this issue, what is the behavior they should add or fix? 
6. On the right-hand side of the window, you have several options that you can configure.  
   • Assignee: Assign someone to work on this issue directly. You can even assign yourself to show what you’re working on. 
   • Labels: Classify your issue into one of several predesigned categories or potentially add a new one. 
   • Type: Indicate whether your issue is about something like a bug or a task. 
   • Projects: Add your issue to projects, which we’ll be covering later in this post. 
   • Milestone: Assign your issue to a specific milestone. 
7. Click the green Create button below the issue description. 

Congratulations! You have just created your first issue! Once an issue is created, anyone on the team can jump in and comment. All they need to do is enter some text in the comment field and then click the Comment button. You can even link issues together by typing # and then the number of the issue in the comment field. GitHub will automatically provide a clickable link to the numbered issue. This is super handy for tracking related work.

And when the work is finished, you can close the issue, letting the entire team know that it’s been addressed.

Creating your first GitHub Project

Projects give you a way to group GitHub Issues together in a visual dashboard that’s perfect for planning, organizing, and tracking work. It’s a tool for breaking big goals down into manageable tasks that you can track all in one place.

Now let’s walk through creating a project board. Here’s a sample repository where you can try this out, or you can do it in your own repository. If you still have the repository open from the walkthrough above, you can skip the first step.

1. Navigate to gh.io/gfb-issues in your browser.
2. At the top of the page, click the Projects tab.
3. In the top-right of the window, click the green New project button.
4. A window will pop up providing several templates for you to start from. Select the Kanban template.
5. Enter a title in the “Project name” field.
6. Unselect the checkbox for Bulk import items.
7. At the bottom of the window, select Create project.

GitHub will now create the project for you and take you to the project view. You’ll see the name of your project at the top of the window. In addition, GitHub automatically created columns for you, but you can customize them however you want.

Notice that underneath your project’s name, there are several tabs. These correspond to different views of the project board. Feel free to click on them to see what the different views look like in your project.

To manage your project board, click the three dots in the top-right corner and select Settings. This opens a new page where you can:

• Manage who has access to your project board.
• Create custom fields.
• Update any current fields.
• Change your project name.
• Provide or change the project description.
• Include a README.
• Create a copy of your project board.
• Change the visibility of your project.

To customize charts

At the top of the window, select the Insights button. On the following page, you’ll be able to view, create, and customize charts. You can change the layout of any of your charts by clicking the Configure button and choosing options from the dropdown menus.

To check the status of workflows

Going back to the main window, you can see a Workflows button next to the Insights button on the top. Select the Workflows button. Now you can see several built-in workflows on the left side of the window that you can use to update the status of items based on certain events. For example, you can automatically set the status to todo when an item is added to your project, close issues when the issue’s status in your project is changed or set the status to Done when an issue is closed.

To add a status update

Going back to the main project view once again, select the Add status update button at the very top. This opens a window where you can add a status report of your project’s health and progress.

Connecting issues and projects

Combining issues and projects together is how you’re able to get a complete view of your work. Think of issues as individual tasks, and projects as the dashboard that organizes those tasks. When you link issues to a project board, you can visualize where everything stands at a glance.

Go ahead and open your project board if it isn’t open already. At the bottom of the window, select Add item. You can either create a new issue right here, or you could search for existing ones. Click the plus icon and select Add item from repository. Select the issue or issues that you want to add to this project board. You can use the checkbox at the top of the list to automatically select all items at once if you want to add them all.

Once you’ve selected the issues you want to add, press the Add elected items button at the bottom of the window. Notice how this adds all of the selected issues to your project board as cards. You can select the cards and move them between status columns as work progresses. You can also click on the issue to see the full details of the issue.

And here’s something cool. The issue and your project board are now synchronized. When you change the status of the issue in one, it will automatically be reflected in the other. You can move multiple issues at once, organizing them into columns that match your workflow, and get that satisfying feeling when you finally move them into the “Done” column.

End-to-end flow

Let’s now simulate a real workflow that you might use in your team project by going through the following steps.

1. Navigate to your project board if you are not already there.
2. Click Add item at the bottom of your first column, indicating that you are adding a new issue to your workflow.
3. Click the plus icon and select Create new issue from the context menu.
4. Enter a title and description for the issue, describing a new feature you want to add.
5. Select Create to create the issue and automatically add it to the project board.
6. Underneath the description, select Labels and select enhancement from the list of options.
7. Click the issue in the project board to open it.
8. In the right-hand column, click the gear next to “Assignees” to assign this issue to someone on your team.
9. Add comments to the issue to signify making progress or providing updates.
10. Now let’s say that some work was done to address this issue. Open a pull request, and in the comment field, mention that it closes the relevant issue. Do this by entering Closes # and then the number connected with the issue in the pull request description. This will automatically connect to the issue and provide a link to it for ease of reference.
11. Merge the pull request, and it will automatically close the issue.

This workflow keeps everyone aligned without the need for constant status meetings. Everything you need to know is there, both in the issue and on the project board!

What’s next?

Now you know how to use GitHub Issues and Projects to organize your work with GitHub. Start simple with a few issues, build out your project board as you go, and you’ll have a system that scales with your team.

If you want to learn even more about GitHub Issues and GitHub Projects, make sure to check out our documentation.

Happy coding!

The post GitHub for Beginners: Getting started with GitHub Issues and Projects appeared first on The GitHub Blog.