Handling and writing bug reports for GitHub

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. While our approach isn’t the only one, we’re sharing how we think in the hopes that it will help you write your next report, for GitHub.com or for a project you’re working on.

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?

Direct any of your bug reports to our Contact Form. Once a bug report is submitted, 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 get a speedy resolution of your issue!

  • Behavior
    • What are the expected and actual behaviors? How are they different?
    • Is there documentation for the expected behavior?
  • Instruction
    • 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?
  • Demonstration
    • For GitHub.com
      • 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, we love to hear them! We’ll share these thoughts with the rest of the team, but we can’t promise to make any specific changes.

If the behavior is unexpected, it’s a bug. We’ll let you know and open an internal issue to inform the responsible team. We’ll let you know about any workarounds. 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 https://github.com/francisfuzz. 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 Contact Form and populate the subject field 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 & 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!

- francisfuzz

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 https://github.com/isaacs/github/issues/6 (perhaps via https://github.com/isaacs/github/issues/924 ) would be ideal for most users, IMHO.