Skip to main content

Creating an issue

In this article

Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow.

Who can use this feature

People with read access can create an issue in a repository where issues are enabled.

Issues can be used to keep track of bugs, enhancements, or other requests. For more information, see "About issues."

Repository administrators can disable issues for a repository. For more information, see "Disabling issues."

Creating an issue from a repository

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Issues.

    Issues tab

  3. Click New issue. New Issues button

  4. If your repository uses issue templates, click Get started next to the type of issue you'd like to open. Select the type of issue you want to create Or, click Open a blank issue if the type of issue you'd like to open isn't included in the available options. Link to open a blank issue

  5. Type a title and description for your issue. A sample issue

  6. If you're a project maintainer, you can assign the issue to someone, add it to a project board, associate it with a milestone, or apply a label.

  7. When you're finished, click Submit new issue.

Creating an issue with GitHub CLI

GitHub CLI is an open source tool for using GitHub from your computer's command line. When you're working from the command line, you can use the GitHub CLI to save time and avoid switching context. To learn more about GitHub CLI, see "About GitHub CLI."

To create an issue, use the gh issue create subcommand. To skip the interactive prompts, include the --body and the --title flags.

gh issue create --title "My new issue" --body "Here are more details."

You can also specify assignees, labels, milestones, and projects.

gh issue create --title "My new issue" --body "Here are more details." --assignee @me,monalisa --label "bug,help wanted" --project onboarding --milestone "learning codebase"

Creating an issue from a comment

You can open a new issue from a comment in an issue or pull request. When you open an issue from a comment, the issue contains a snippet showing where the comment was originally posted.

  1. Navigate to the comment that you would like to open an issue from.
  2. In that comment, click . Kebab button in pull request review comment
  3. Click Reference in new issue. Reference in new issue menu item
  4. Use the "Repository" drop-down menu, and select the repository you want to open the issue in. Repository dropdown for new issue
  5. Type a descriptive title and body for the issue. Title and body for new issue
  6. Click Create issue. Button to create new issue
  7. If you're a project maintainer, you can assign the issue to someone, add it to a project board, associate it with a milestone, or apply a label.
  8. When you're finished, click Submit new issue.

Creating an issue from code

You can open a new issue from a specific line or lines of code in a file or pull request. When you open an issue from code, the issue contains a snippet showing the line or range of code you chose. You can only open an issue in the same repository where the code is stored.

Code snippet rendered in an issue opened from code

  1. On GitHub.com, navigate to the main page of the repository.
  2. Locate the code you want to reference in an issue:
    • To open an issue about code in a file, navigate to the file.
    • To open an issue about code in a pull request, navigate to the pull request and click Files changed. Then, browse to the file that contains the code you want included in your comment, and click View.
  3. Choose whether to select a single line or a range:
    • To select a single line of code, click the line number to highlight the line. File with a single line of code selected
      • To select a range of code, click the number of the first line in the range to highlight the line of code. Then, hover over the last line of the code range, press Shift, and click the line number to highlight the range. File with a range of code selected
  4. To the left of the code range, click . In the drop-down menu, click Reference in new issue. Kebab menu with option to open a new issue from a selected line
  5. Type a title and description for your issue. A sample issue
  6. If you're a project maintainer, you can assign the issue to someone, add it to a project board, associate it with a milestone, or apply a label.
  7. When you're finished, click Submit new issue.

Creating an issue from discussion

People with triage permission to a repository can create an issue from a discussion.

When you create an issue from a discussion, the contents of the discussion post will be automatically included in the issue body, and any labels will be retained. Creating an issue from a discussion does not convert the discussion to an issue or delete the existing discussion. For more information about GitHub Discussions, see "About discussions."

  1. Under your repository or organization name, click Discussions. "Discussions" tab for a repository
  2. In the list of discussions, click the discussion you want to view. Discussion in list of discussions for a repository
  3. In the right sidebar, click Create issue from discussion. Button to create issue from discussion
  4. Type a title and description for your issue. A sample issue
  5. If you're a project maintainer, you can assign the issue to someone, add it to a project board, associate it with a milestone, or apply a label.
  6. When you're finished, click Submit new issue.

Creating an issue from a project

You can quickly create issues without leaving your project. When using a view that is grouped by a field, creating an issue in that group will automatically set the new issue's field to the group's value. For example, if you group your view by "Status", when you create an issue in the "Todo" group, the new issue's "Status" will automatically be set to "Todo." For more information about Projects, see "About Projects."

  1. Navigate to your project.

  2. At the bottom of a table, group of items, or a column in board layout, click .

    Screenshot showing + button at the bottom of the project

  3. Click Create new issue.

    Screenshot showing "Create new issue" menu item

  4. At the top of the "Create new issue" dialog, select the repository where you want the new issue to be created.

    Screenshot showing the repository dropdown menu

  5. Below the repository dropdown, type a title for the new issue.

    Screenshot showing the issue title field

  6. Optionally, use the fields below the title field to set assignees, labels, and milestones, and add the new issue to other projects.

    Screenshot showing the assignee, label, project, and milestone options

  7. Optionally, type a description for your issue.

    Screenshot showing the description field

  8. Optionally, if you want to create more issues, select Create more and the dialog will reopen when you create your issue.

    Screenshot showing the create more checkbox

  9. Click Create.

    Screenshot showing the create button

Creating an issue from a classic project note

If you're using a classic project to track and prioritize your work, you can convert notes to issues. For more information, see "About projects (classic)" and "Adding notes to a classic project."

Creating an issue from a task list item

Within an issue, you can use task lists to break work into smaller tasks and track the full set of work to completion. If a task requires further tracking or discussion, you can convert the task to an issue by hovering over the task and clicking in the upper-right corner of the task. For more information, see "About task lists."

Creating an issue from a URL query

You can use query parameters to open issues. Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results or an issue template on GitHub. To create your own query parameters, you must match the key and value pair.

Tip: You can also create issue templates that open with default labels, assignees, and an issue title. For more information, see "Using templates to encourage useful issues and pull requests."

You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to add a label to an issue to use the labels query parameter. For more information, see "Repository roles for an organization."

If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the URL will return a 404 Not Found error page. If you create a URL that exceeds the server limit, the URL will return a 414 URI Too Long error page.

Query parameterExample
titlehttps://github.com/octo-org/octo-repo/issues/new?labels=bug&title=New+bug+report creates an issue with the label "bug" and title "New bug report."
bodyhttps://github.com/octo-org/octo-repo/issues/new?title=New+bug+report&body=Describe+the+problem. creates an issue with the title "New bug report" and the comment "Describe the problem" in the issue body.
labelshttps://github.com/octo-org/octo-repo/issues/new?labels=help+wanted,bug creates an issue with the labels "help wanted" and "bug".
milestonehttps://github.com/octo-org/octo-repo/issues/new?milestone=testing+milestones creates an issue with the milestone "testing milestones."
assigneeshttps://github.com/octo-org/octo-repo/issues/new?assignees=octocat creates an issue and assigns it to @octocat.
projectshttps://github.com/octo-org/octo-repo/issues/new?title=Bug+fix&projects=octo-org/1 creates an issue with the title "Bug fix" and adds it to the organization's project board 1.
templatehttps://github.com/octo-org/octo-repo/issues/new?template=issue_template.md creates an issue with a template in the issue body. The template query parameter works with templates stored in an ISSUE_TEMPLATE subdirectory within the root, docs/ or .github/ directory in a repository. For more information, see "Using templates to encourage useful issues and pull requests."

You can also use URL query parameters to fill custom text fields that you have defined in issue form templates. Query parameters for issue form fields can also be passed to the issue template chooser. For more information, see "Syntax for GitHub's form schema."

Creating an issue from a code scanning alert

Note: The tracking of code scanning alerts in issues is in beta and subject to change.

This feature supports running analysis natively using GitHub Actions or externally using existing CI/CD infrastructure, as well as third-party code scanning tools, but not third-party tracking tools.

If you're using issues to track and prioritize your work, you can use issues to track code scanning alerts. For more information about creating issues to track code scanning alerts, see "Tracking code scanning alerts in issues using task lists."

Further reading