Quickstart for GitHub Issues - GitHub Docs Skip to main content GitHub Docs Version: Free, Pro, & Team Search or ask Copilot Search or ask Copilot Select language: current language is English Search or ask Copilot Search or ask Copilot Open menu Collapse sidebar Expand sidebar Scroll breadcrumbs left * Home * GitHub Issues * Issues * Learning about issues * Quickstart for GitHub Issues Scroll breadcrumbs right GitHub Issues * * * Issues * Learning about issues * About issues * Quickstart for GitHub Issues * Planning and tracking work for your team or project * Using issues * Create an issue * Adding sub-issues * Creating issue dependencies * Assign issues & PRs * Editing an issue * View all issues & PRs * Browsing sub-issues * Filter and search * Create branch for issue * Link PR to issue * About slash commands * Managing issue types * Managing issue fields * Using issue fields * Administering issues * Triage an issue * Pin an issue * Marking issues or pull requests as a duplicate * Transfer an issue * Close an issue * Deleting an issue * Clone an issue * Projects * Learning about Projects * About Projects * Quickstart for Projects * Best practices for Projects * Creating projects * Creating a project * Copying a project * Managing items in your project * Adding items * Converting draft issues * Editing items * Archiving items * Understanding fields * About text and number fields * About date fields * About single select fields * About iteration fields * About issue fields * About sub-issue fields * About pull request fields * About the issue type field * Renaming custom fields * Deleting custom fields * Customizing views * Changing the layout * Customizing tables * Customizing boards * Customizing roadmaps * Filtering projects * Managing your views * Automating projects * Using built-in automations * Automating with the API * Automating with Actions * Adding items automatically * Archiving items automatically * Viewing insights * About insights for Projects * Creating charts * Configuring charts * Managing your project * Managing project visibility * Managing project access * Managing templates * Closing and deleting projects * Adding a project to a repo * Adding a project to a team * Exporting your project data * Finding your projects * Sharing project updates * Labels and milestones * Managing labels * About milestones * Create & edit milestones * Add to milestones * Filter by milestone * View progress to milestone Quickstart for GitHub Issues Follow this brief interactive guide to learn about GitHub Issues. Copy as Markdown In this article * Introduction * Prerequisites * Opening a blank issue * Filling in information * Adding a task list * Assigning the issue * Adding labels * Adding issue types * Adding the issue to a project * Adding milestones * Submitting your issue * Adding sub-issues * Adding issue dependencies * Communicating * Next steps Introduction This guide demonstrates how to use GitHub Issues to plan and track a piece of work. In this guide, you will create a new issue and break it down into sub-issues. You'll also learn how to add labels, issue types, milestones, assignees, and projects to communicate metadata about your issue. Prerequisites To create an issue, you need a repository. You can use an existing repository that you have write access to, or you can create a new repository. The repository must have issues enabled. For more information about creating a repository, see Creating a new repository . For more information about enabling issues if they are disabled in your repository, see Disabling issues . Opening a blank issue First, create an issue. There are multiple ways to create an issue; you can choose the most convenient method for your workflow. This example will use the GitHub UI. For more information about other ways to create an issue, see Creating an issue . * On GitHub, navigate to the main page of the repository. * Under your repository name, click Issues . * Click New issue . * In this example, we will start with a blank issue. Your repository may use issue templates and issue forms to encourage contributors to provide specific information. If your repository uses issue templates, click Open a blank issue . Filling in information Give your issue a descriptive title. The title should convey at a glance what the issue is about. Add a description that explains the purpose of the issue, including any details that might help resolve the issue. For example, if this is a bug report, describe the steps to reproduce the bug, the expected result, and the actual result. You can use markdown to add formatting, links, emojis, and more. For more information, see Writing on GitHub . Adding a task list You can also use plain text to track tasks that don't have a corresponding issue and convert them to issues later. For more information, see About tasklists . Assigning the issue To communicate responsibility, you can assign the issue to a member of your organization. See Assigning issues and pull requests to other GitHub users . Adding labels Add a label to categorize your issue. For example, you might use a question label and a good first issue label to indicate that an issue is a question that a first-time contributor could pick up. Users can filter issues by label to find all issues that have a specific label. You can use the default labels, or you can create a new label. For more information, see Managing labels . Adding issue types You can add an issue type to classify work across the organization. See Managing issue types in an organization . Adding the issue to a project You can add the issue to an existing project and populate metadata for the project. For more information about projects, see About Projects . Adding milestones You can add a milestone to track the issue as part of a date based target. A milestone shows the progress of the issues as the target date approaches. See About milestones . Submitting your issue Click Submit new issue to create your issue. You can edit any of the above fields after creating the issue. Your issue has a unique URL that you can share with team members, or reference in other issues or pull requests. Adding sub-issues You can add sub-issues to an issue to quickly break down larger pieces of work into smaller issues. Sub-issues add support for hierarchies of issues on GitHub by creating relationships between your issues. You can create multiple levels of sub-issues that accurately represent your project by breaking down tasks into exactly the amount of detail that you and your team require. See Adding sub-issues and Browsing sub-issues . Adding issue dependencies You can define blocking relationships between issues using issue dependencies. Issue dependencies let you identify issues that are blocked by, or blocking, other work. See Creating issue dependencies . Communicating After your issue is created, continue the conversation by adding comments to the issue. You can @mention collaborators or teams to draw their attention to a comment. To link related issues in the same repository, you can type # followed by part of the issue title and then clicking the issue that you want to link. For more information, see Writing on GitHub . Next steps You can use issues for a wide range of purposes. For example: * Tracking ideas * Collecting feedback * Planning tasks * Reporting bugs To break your issue down into more manageable tasks, you can add multiple levels of sub-issues. See Adding sub-issues . Here are some helpful resources for taking your next steps with GitHub Issues: * To learn more about issues, see About issues . * To learn about the essentials for using GitHub's planning and tracking tools, see Planning and tracking work for your team or project . * To learn more about how projects can help you with planning and tracking, see Learning about Projects . * To learn more about using issue templates and issue forms to encourage contributors to provide specific information, see Using templates to encourage useful issues and pull requests . Back to top Help and support Was this Doc helpful? Yes No Help us make GitHub Docs great! All Docs are open source. See something that's wrong or unclear? Submit a pull request. Make a contribution Still need help? Ask the GitHub community Contact support Expert services Blog GitHub Inc. © 2026 Terms Privacy Status Pricing