Submitting bug reports for

Are you frustrated because your bug reports don’t get fixed or are misunderstood? Learn how you can get things fixed quicker by framing software issues in an understandable and actionable way.

GitHub Support receives a variety of reports ranging in type, frequency, and quality every day. We’re sharing how we approach the reports we receive in the hopes that it will help you write your next report for (and you could possibly apply some of these strategies for reporting a bug on project you’re working on, too!).

What’s a bug report?

A bug report is a write-up that describes a situation where existing behavior contradicts expected (but not always documented) behavior.

Bug reports are different from feature requests. Feature requests focus on introducing a new feature that has yet to exist or expanding an existing feature’s scope with more functionality.

How do I submit one?

It depends on the report! :wink:

  • If your report involves any sensitive data, the best place to report that is through our Contact Form.
  • If you’ve found a security vulnerability, our GitHub Security team would :heavy_heart_exclamation: to hear from you. Check out our GitHub Security Bug Bounty for more details.
  • For anything else on, open a new topic in the relevant category that describes your experience of existing behavior contradicting expected (but not always documented) behavior.

Once opened, a member of the GitHub Support Team will follow up with additional questions or an evaluation of your report.

How does GitHub Support handle and write bug reports?

When GitHub Support receives a bug report, we have two goals: understanding and evaluation. The whole process can be summarized in the following acrostic, BIDE:

  • Behavior
  • Instruction
  • Demonstration
  • Evaluation

One could say that we BIDE our time to understand what’s being reported before reaching any conclusions. :wink:


To develop a clear understanding of the problem, we ask ourselves the following questions about behavior, instruction, and demonstration.

If your bug report doesn’t include enough information for us to answer every question, we may need to follow up with you before making an evaluation. Answering these questions in your bug report is the best way to help one of our support engineers get up to speed!

  • What are the expected and actual behaviors? How are they different?
  • Is there documentation for the expected behavior?
  • Are there instructions for reproducing the problem?
  • When (date & time) and where (exact URL) did the problem occur?
  • Was the user logged in or authenticated?
  • For
    • are there screenshots or a motion picture (GIF) demonstrating what happened?
    • are there any textual logs showcasing server errors from the browser’s console?
  • For the GitHub API: are there any curl -v outputs that demonstrate the issue at hand?

The last part of the process is evaluation: is the reported behavior expected or a bug?

If the behavior is expected, we provide an explanation and accompanying documentation if available. If you have thoughts about how the behavior could be improved, our team would love to hear them! Our product team tracks the requests through our official product feedback form.

If the behavior is unexpected, we’ll acknowledge it and open an internal issue to inform the responsible team. If there are any workarounds or alternatives, we’ll do our best to tell you. We can’t make any promises or offer a timelines for any fixes, but we are always open to answering any follow-up questions in the meantime.

The Anatomy of an internal bug report

We’re sharing how we write bug reports to offer you another perspective for framing future issues. If your bug report is confirmed by our team, we open a new GitHub Issue in the appropriate repository.

The issue title serves as a “first impression” to the reader.

The issue body includes the following items:

  • @mention to the responsible team(s)
  • a link to the original report for context
  • a summary of the expected and actual behaviors
  • steps for reliably reproducing the actual behavior
  • an accompanying demonstration (usually in the form of screenshots or a GIF)

Once the issue is created, the responsible team triages it and offers input, be it a fix in the form of a pull request, a workaround in lieu of an immediate fix, or additional questions to gain a better understanding of the issue at hand.

Example of putting it all together

Here’s an example of the entire bug discovery and report process.

Imagine I log in and navigate to my profile page at When I attempt to load that page, the page loads a unicorn and a message that the page is taking too long to load. If I log out and navigate to my profile page, I don’t see the unicorn anymore.

I navigate to the How to Use Git and GitHub category, press :heavy_plus_sign: New Topic, and populate the title with the following text:

Navigating to my user profile returns a Unicorn (page is timing out)

Under “How can we help?”, I describe my experience:

Hi GitHub Support!

When I navigate to my user profile, the page loads a unicorn and let’s me know that it’s taking way too long to load:

This is unexpected behavior because I expect to see my profile as it’s documented here:

Also, I noticed that I only see the unicorn when I’m logged in. If I’m logged out, I don’t see the unicorn anymore.

Here’s a screenshot of what I’m seeing:


Could you let me know if you have any workarounds to this? Thanks for all your help!

With this information, a GitHub Support Team member can try to reproduce the issue themselves and pass on the bug report to the appropriate team.

What do you think?

How do you write your bug reports? We’d love to hear your thoughts. Maybe we can improve the way we do things!


Still, implementing (perhaps via ) would be ideal for most users, IMHO.

GitHub no longer accepts bug reports at the contact form linked in this the first post of this topic.

Does anyone know where they should go instead?

Hi @sharpobject! Welcome to the community.

I see that our support team has reached out regarding the bug report that you submitted. You may want to check spam or other inbox filters for their reply if you have not already. Thank you for sharing your report with us!

Hi @nyahbhinghiprincess,

What’s the appropriate place to submit bug reports? The contact form I used has 9 categories none of which are about bug reports. Here’s a screenshot of the categories

1 Like

Hi @sharpobject, thank you for the feedback on those tiles. I passed it along to the appropriate teams. Presently our support team escalated and categorized the bug report that you sent it in. Our apologies on the lack of clarity in that experience! Thank you still for taking the time to send in a report.

Hi @nyahbhinghiprincess,

What about the rest of us with a bug to report ?

Hi @ydirson and welcome to the community. You can still follow the guidance from the Protips article above

That’s what’s written in various places, and it looks like I’m not the only one not seeing in this contact form how to report a bug. The only seemingly-relevant option there seems to be the link to this forum.

1 Like

:wave: @sharpobject, @ydirson–– hello there! Francis here, I work with @nyahbhinghiprincess and wanted to follow up.

I wrote this article about 2 years ago and after re-reading it in 2020, much has changed since then. As a next step, I’m taking some time this week to revise the content with updated guidance. My apologies for any confusion there!

As @sharpobject shared earlier, there are a number of different topics that you can choose from. To be clear, reporting unexpected behavior with one of’s feature is not one of them (though that idea is something our team maintaining this feature is aware of).

The next best thing you can do is to open a new topic in the relevant category if you encounter any unexpected behavior (within the reasonable bounds of sensitivity). From there, someone from the community may comment and try reproducing that behavior to confirm it. Once confirmed, our support engineering team will appropriately relay it to the team that maintains the feature internally (see Codespace fails to connect: 502 and Bug? Project not showing network dependents for recent examples).

We don’t recommend selecting one of those topics and reporting the unexpected behavior that way, as our team will redirect you back to the GitHub Community Forum encouraging you to create (or add to an existing) topic.

For what it’s worth, if you’ve found a security vulnerability, our GitHub Security team would :heavy_heart_exclamation: to hear from you. Check out our GitHub Security Bug Bounty for more details.

I hope this helps! I’ll post an update again on this thread once I’ve updated the above copy. :v:

1 Like

Hey @francisfuzz, thanks for the details here. I’ll add my $0.02 that not having a way to file bugs - only via the forum - is pretty frustrating; I’ve found what seems to be a bug in Github Actions but with the above steps the only action available to me is hoping that someone from the Github team notices my thread. How do we go about flagging these bugs to the Github team?