Installation

Connect a GitHub repository, add one script tag, then send a test report. No npm package or backend setup is required for the hosted service. Allow time for any organization approval, site deployment, and testing your setup needs.

Step 1: Install the GitHub App

BugDrop needs access to your GitHub repository to create issues and store screenshots. Install the official GitHub App to grant these permissions.

Install BugDrop from GitHub Marketplace

During installation you will be asked which repositories to grant access to. Choose Only select repositories and select the repository that should receive feedback to limit the app’s access. Organization installations may require an administrator’s approval.

What permissions does the app request?

PermissionAccess LevelPurpose
IssuesRead & WriteCreate bug reports as GitHub Issues
ContentsRead & WriteStore screenshots and attachments in the repository
MetadataReadRead basic repository information; included with GitHub App repository access

Contents access includes repository files, including source code. GitHub grants this permission for the selected repository, not just a screenshot folder or branch. It permits reading and writing repository contents, subject to GitHub’s rules; see GitHub’s Contents API documentation.

BugDrop uses it to store screenshots and attachments on the bugdrop-screenshots branch. That describes the implementation’s use, not a narrower permission grant. Review Security before installing. You can change selected repositories or revoke access under GitHub Settings > Applications > Installed GitHub Apps.

Step 2: Add the Script Tag

Add the BugDrop script tag to your HTML, just before the closing </body> tag:

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
  data-repo="your-username/your-repo"
></script>

Replace your-username/your-repo with your actual GitHub repository path (e.g., acme-corp/my-website).

These installation examples use widget.v1.56.4.js so you can test a specific version before updating. The unversioned widget.js URL follows the current hosted deployment automatically. See version pinning for update options and hosting-availability limits, and use the same URL throughout your integration.

Full HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <!-- Your site content here -->

  <!-- BugDrop widget -->
  <script
    src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
    data-repo="your-username/your-repo"
  ></script>
</body>
</html>

Customized Example

You can add data attributes to customize the widget's appearance and behavior:

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
  data-repo="your-username/your-repo"
  data-theme="dark"
  data-position="bottom-left"
  data-color="#6366f1"
  data-locale="nl"
  data-welcome="We'd love your feedback!"
></script>

Set data-locale to choose the widget language explicitly, or omit it to let BugDrop infer the language from your page's <html lang> attribute.

See the Configuration and Styling docs for all available attributes.

Protecting sensitive data

If your page renders customer data, billing details, or any other content you want BugDrop to visually cover in supported screenshot modes, mark those elements with data-bugdrop-mask:

<div class="customer-row" data-bugdrop-mask>
  Jane Doe — [email protected]
</div>

BugDrop covers each marked element with an opaque rectangle on supported captured screenshots. Password inputs and credit-card autocomplete fields are masked automatically. See Screenshot masking on the Security page for details.

Step 3: Send a Test Report

Load your page, open the BugDrop button, and submit a clearly labeled test report with a screenshot. Confirm that the issue arrives in the selected repository and that its screenshot opens. A visible widget alone does not confirm that repository permissions, screenshot storage, and submission are working.

Reports and screenshots in a public repository are public. Use non-sensitive test content, and review screenshot masking before using BugDrop on pages with customer data.

Important Notes

Preserve the widget's loading contract

Use a normal script element without async or defer. The widget reads configuration from the executing script element, so changing execution order can separate initialization from its data-* attributes. This is the contract in the official BugDrop README and the same contract used by BugDrop's own website.

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
  data-repo="owner/repo"
></script>

Content Security Policy (CSP)

If your site uses a Content Security Policy, allow the BugDrop worker domain in your CSP directives:

Content-Security-Policy: script-src 'self' https://bugdrop.neonwatty.workers.dev;

If you have a strict CSP, make sure the BugDrop worker domain is included in your script-src directive.

Branch Protection and the Screenshots Branch

BugDrop stores screenshots in a dedicated branch called bugdrop-screenshots in your repository. This branch is created automatically when the first screenshot is uploaded.

Treat this branch as user-generated content storage. Exclude bugdrop-screenshots from CI/deploy workflows and keep privileged workflows limited to main or other trusted branches.

If you use branch protection rules, make sure the BugDrop GitHub App has permission to push to the bugdrop-screenshots branch. You can do this by either:

  1. Excluding the branch from protection rules -- Add bugdrop-screenshots to the exclusion list in your branch protection settings
  2. Allowing the app to bypass protection -- Add the BugDrop GitHub App (neonwatty-bugdrop) to the list of actors that can bypass branch protection

Without this, screenshot uploads will fail silently, though the issue itself will still be created.

Framework-Specific Notes

Next.js App Router: Render the normal script element near the end of the root layout body. Do not use next/script, because its loading strategies intentionally change when the script is injected or executed. Place the widget in one shared layout, not both a root and nested layout:

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <script
          src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
          data-repo="your-username/your-repo"
        />
      </body>
    </html>
  );
}

For a preview-only Vercel workflow, render this element only when the server-side VERCEL_ENV value is preview; see the tested Vercel preview guide.

Verifying the Installation

After adding the script tag, verify the current public contract: window emits bugdrop:ready, the page contains #bugdrop-host, and its open Shadow DOM contains .bd-trigger. The CI testing guide has an executable Playwright check.

If you see any errors, check that:

  1. The data-repo attribute matches your GitHub repository path exactly
  2. The GitHub App is installed on that repository
  3. Your CSP (if any) allows the required domains
  4. The script request returns JavaScript rather than an HTML error page

You can also test by clicking the bug button and submitting a test report. Check your GitHub repository's Issues tab to confirm it was created successfully.

Next Steps