Capture, annotate, and file bug reports to GitHub in one click.
A Chrome extension (Manifest V3) designed to streamline the bug-reporting workflow for QA teams and developers.
BugShot is a Chrome extension that lets developers capture, annotate, and file bug reports directly to GitHub Issues in one workflow — without switching tabs, copying URLs, or manually writing environment details.
- Introduction
- Visual Overview
- Core Features
- Automated Report Data
- DevTools Panel
- GitHub Integration
- UX Details
- Architecture
- Setup
- How Screenshots Are Attached
- Known Limitations
- Permissions Used
Highlight issues using the integrated drawing suite. Support for rectangles, arrows, and text notes with built-in cropping capabilities.
The extension automatically populates environment metadata, recorded steps, and console logs into a structured form.
One-click submission creates a standardized issue in the target repository with embedded screenshots and technical metadata.
- Viewport Capture: Capture the visible viewport with one click.
- Full-Page Capture: Automated scrolling and stitching of tiles into a single high-resolution image.
- Crop Tool: Drag-select any region of the screenshot before starting the annotation process.
- Annotation Suite: Freehand pen, rectangle, arrow, and text labels.
- Color Selection: Four professional colors (Red, Yellow, Blue, White).
- History Control: Per-stroke undo and a clear-all function to revert to the original capture.
- Console Screenshot: Optional secondary capture with a 3-second countdown to facilitate capturing DevTools.
- Steps to Reproduce: Automatically records the last 20 user interactions (clicks with element descriptions, SPA navigations) to populate report steps.
- Console Capture: Intercepts console errors, warnings, and unhandled promise rejections from the page's main JavaScript context.
- Network Failure Capture: Monitors 4xx/5xx responses and connection errors from both fetch and XMLHttpRequest.
- Environment Metadata: Automatically collects URL, browser version, OS, screen resolution, viewport size, and timestamp.
BugShot includes a dedicated tab within Chrome Developer Tools:
- Live Monitoring: Displays console errors and network failures as they occur.
- Native Integration: Utilizes the network request API for real-time data inspection.
- Background Sync: Data auto-syncs to the background worker every 2 seconds to ensure the popup is always current.
- One-Click Filing: Includes a button to save all current session logs for the next report.
- Direct API Submission: Submits issues directly to GitHub via the REST API using a Personal Access Token.
- Screenshot Storage: Uploads annotated images to a
.bugshot/directory in the target repository. - Rich Markdown Formatting: Issue bodies include screenshots, severity indicators, reproduction steps, environment tables, and error sections.
- Responsive Inputs: All text fields automatically resize as the user types.
- Persistence: Extension settings are persisted across browser sessions via local storage.
- Status Notifications: Integrated toast notifications for confirmation of success or detailed error reporting.
- Synchronous Undo: The annotation canvas uses image data snapshots to ensure reliable undo operations without race conditions.
manifest.json — MV3, declares devtools_page, content_scripts, background
background.js — Service worker: tab capture, full-page stitch, GitHub API, data bridge
content/content.js — Isolated world: click/nav recording, message handler, sessionStorage reader
content/main_world.js — Main world (injected): console + fetch/XHR interception
devtools/devtools.js — DevTools context: panel creation, network monitoring, sessionStorage sync
devtools/panel.html/js — BugShot tab UI inside DevTools
popup/popup.html/css/js — Main extension UI: capture, annotate, crop, report form, settings
- Clone the Repository:
git clone https://github.com/Yash55-max/BugShot.git
- Load the Extension:
- Microsoft Edge: Navigate to
edge://extensions, enable Developer mode, and click Load unpacked. - Google Chrome: Navigate to
chrome://extensions, enable Developer mode, and click Load unpacked. - Select the
bugreport-extdirectory from the cloned repository.
- Microsoft Edge: Navigate to
- Configuration:
- Open the Settings (Gear Icon) in the BugShot popup.
- Provide a GitHub Personal Access Token with
reposcope. - Enter the target GitHub Owner and Repository Name.
BugShot commits screenshots as PNG files into a .bugshot/ directory in your repository using the Contents API. The resulting download URL is embedded as a standard markdown image in the issue body.
Note: You may add .bugshot/ to your .gitignore to keep the repository clean while allowing images to render correctly in GitHub issues.
- Script Blocking: Console capture may be limited on pages that entirely block extension script injection (e.g., highly restrictive CSPs).
- Fixed Headers: Full-page capture uses tile stitching; pages with fixed headers may show repetition at tile boundaries.
- DevTools Initialization: If the extension is reloaded, DevTools must be closed and reopened once to reinitialize the BugShot panel.
- Viewport Visibility: Console Screenshot captures the visible tab viewport and works most effectively when DevTools is docked.
| Permission | Reason |
|---|---|
activeTab |
Required to capture the current tab screenshot. |
scripting |
Used to inject the main-world script for console and network capture. |
tabs |
Necessary for full-page scroll capture and tab information. |
storage |
Used to persist GitHub settings and credentials locally. |
host_permissions: <all_urls> |
Allows injection of content scripts across different domains. |
host_permissions: api.github.com |
Required to submit issues and upload images to GitHub. |




