Submitting bug reports for GitHub.com

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 GitHub.com (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 GitHub.com, 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:

Understanding

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!

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?
Evaluation

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 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 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:

https://github.com/francisfuzz

This is unexpected behavior because I expect to see my profile as it’s documented here: https://help.github.com/articles/about-your-profile/

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:

unicorn

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!

10 Likes

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.

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 GitHub.com’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?

:newspaper_roll: I’ve updated the copy with the latest guidance. Thanks for your patience everyone!


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?

:wave: @mieubrisse––Hi there! Thanks for following up. I appreciate what you’ve shared here because it helps me understand where you’re coming from.

Outside of what’s written in a topic’s subject and body, there’s not a specific way to “flag” these for our team to review.

However, I can see how having such an indicator could be beneficial for the support engineers on my team––they could use it as a way to quickly surface these reports and appropriately escalating them to the appropriate team.

I’ll bring it up with them and while I don’t have any timeline for any new changes, we’re open to hear suggestion from you and the wider community around this flow. :ear:

1 Like

I’m a bit confused by the information provided in this post.

If I have understood it correctly, to report a bug about Github, I should create a post on the Community Forum, as mentioned on the Contact Form. Does this mean the Community can make those bugfixes?

:wave: @dragondive - great question! If you have a bug report about GitHub.com, we encourage you to create post in the Community Forum. Once the post is created, the community is welcome to share similar reports or openly troubleshoot the report to determine if what’s reported is unexpected behavior. In addition, our team of support engineers are monitoring the forum for these reports so confirmed issues can be escalated to the appropriate team.

The source code for GitHub.com (the application) is not publicly available. However, there are some components that the github organization has open sourced for the wider community to benefit from. I hope this helps!

I don’t want to flame but this feels like a joke. I’m trying to report a bug I have in a private repository. Google leads me to the support@github.com Email address. Email there returns saying I shall check https://support.github.com. So here I am. However the How to I submit one part about sensitive data doesn’t work. There is no option where I can report my bug.
Although this is about a private repository I guess I still would have to post this in the public forum.

Very disappointed honestly, even though of course I’m just a student and not a power user.

A little background to the bug: In my private repository another user pops up when I commit which by default should not be possible since the repository is private. Still it happened and it looks like another person committed to my private repository. I don’t know if this person also gains access to my data then this would be a security issue as well.

I’m trying to report a bug I have in a private repository. Google leads me to the support@github.com Email address. Email there returns saying I shall check https://support.github.com. So here I am.

:wave: @matt3o––thanks for sharing that feedback here. GitHub Free user and organization accounts can use this forum to report any unexpected behaviors with GitHub.com (among many other activities), to which one of our support engineers can investigate further. If you have a paid account (like being on the Pro plan), you can contact GitHub Support directly](https://support.github.com/contact).

I see where you’re coming from, and it’s something our team is aware of. We’ll be sure to forward it internally so they’re aware of your feedback. As far as the behavior you’ve reported, I’m reminded of an article one of my colleagues wrote a few years back: Why is my commit associated with the wrong person? Laura’s article is an excellent reference I’ve shared with other customers in the past as a first step toward explaining possible causes for having the wrong person associated with some commit, be it in a public or a private repository.

If the explanations outlined there don’t match up with what you’re seeing, we’d like to kindly ask that you create a new topic in our GitHub Help section. Showing steps for reproducing this on a public repository would help the community and our support engineers investigate it further to evaluate the report.