Installation

Getting BugDrop running on your site takes about 30 seconds. There are only two steps: install the GitHub App and add a script tag. No npm packages, no build configuration, no backend setup required.

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. You can choose specific repositories or grant access to all repositories in your account or organization.

What permissions does the app request?

Permission Access Level Purpose
Issues Read & Write Create bug reports as GitHub Issues
Contents Read & Write Store screenshots in the repository

These are the minimum permissions required for BugDrop to function. The app does not request access to your code, pull requests, actions, or any other repository data.

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.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).

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.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.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: You Are Done

That is it. Load your page and you will see the BugDrop button in the corner of your site. Click it to open the feedback form, fill it out, and submit -- a GitHub Issue will be created in your repository automatically.

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