If you're reading this, it's likely that your team is already using GitHub to collaborate on code. Why not activate the built-in repository issue tracker and log your bugs & feedback there?
However reporting issues in GitHub can prove cumbersome. It can break up your workflow as you constantly have to log into GitHub and document a new issue via the interface (which between you and me, isn't exactly the best UI ever 😉 ) . Furthermore, the issues are often not descriptive enough for developers to understand and reproduce bugs fast enough.
That's why we created Marker.io, the best way to create detailed-rich bug reports in GitHub without leaving your website.
See how Marker.io + Github work together in this video:
If you'd like to set up you own bug reporting & tracking workflow around Marker.io and GitHub follow these easy steps.
Step 1: Activate the GitHub issue tracker
Make sure you the issue tracker is enabled on the repository. By default, GitHub activates the issue tracker on all new repositories. If that is not your case, follow these simple steps:
- Log into your GitHub account and select your repository
- Go in the Settings tab
- Go to the Options tab
- Activate the issue tracker.
Make sure that all the people who will be collaborating on this repository have access in GitHub.
Finally, create priority labels to process bugs in order of priority. You'll see these labels will turn out to be useful later on. We recommend defining 4 labels, but you can pick whatever labels suits your needs :
Once your issue tracker is set up, make sure to invite your team (and clients) to collaborate on this GitHub repo. This will make it easy for everyone to report bugs .
Step 2: Connect your GitHub account
To create bug reports in seconds into your GitHub issue tracker, you will need a Marker.io account. (If you don't have one yet, start your free trial now)
Go to your Marker.io integration admin here and sync up your Trello account.
Now, it’s time to log some issues!
Step 3: Capture a screenshot of the bug
At this point, you should have the Marker.io screen capture extension installed in your browser. (if not, log into your account and install now here)
Now, go to your website and start hunting for bugs. When you find one, click on the Marker.io browser extension and capture a screenshot.
Step 4: Select your repository
After capturing your screenshot, the Marker.io editor will open. In the upper left corner, select in which Trello board and list you want to start sending bug reports.
Marker will automatically remember the last repo used for next time.
Step 5: Annotate to get your point across
Use the built-in annotation tools inside the Marker.io editor to get your point across.
Step 6: Fill out a bug report template
When you're done annotating your screen capture, make sure to document the actual and expected results of the bug. Some bugs might be obvious for you, but your developers won't always know what the final results should look like.
Take the time to fill out the bug report template and your developers will thank you for it! The description will be automatically converted using Markdown in a new GitHub issue.
Step 7: Assign priority & team member
Consider adding a priority level to your bug report to make it manageable for your team to know on what they should work next. You can even add a team member who collaborates with you on this GitHub repository.
Step 8: Create & view the issues in GitHub
When you are ready, hit the big green button that reads "Create issue". Your screenshot will be converted into a GitHub issue in your selected repository and all the information you included will be added to the issue as well.
On top of all this information, Marker automatically grabs the technical information about your browser, OS and screen as well as the original Page URL. Your developers will now be able to easily reproduce the bug and they won't have to ask you again which browser you used or what is the size of your screen. The best part, you didn't have to do anything to.
Here’s an example of a well-documented bug report in GitHub created with Marker.io:
This GitHub issue has all the information needed for your team to act on it:
- The issue is in the correct repository.
- The issue has a priority (using labels).
- The bug is assigned to a team member.
- The annotated screenshot is attached.
- The expected and actual results are well documented.
- The technical browser information is included.
- The URL where the screenshot was captured is in the description.
- The bug has a due date.
Wrapping it up
Invite your team to collaborate in a dedicated GitHub repo and roll out Marker.io to your entire team so anybody can report professional bugs and feedback in seconds without interrupting their workflow.
Wait.... what about bug reporting on Mobile?
Read our special guide about how Marker.io can help with bug reporting on responsive websites and mobile apps