Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions src/content/docs/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,10 @@ These attributes control the fundamental behavior of the widget.
| `data-label` | `"Feedback"` | Text label displayed next to the button icon |
| `data-category-labels` | built-in labels | Self-hosted JSON mapping from built-in categories to GitHub labels |
| `data-button` | `"true"` | Show the floating button: `"true"` or `"false"` |
| `data-auth-token-provider` | none | Name of a global function that returns a self-hosted auth token |
| `data-welcome` | `"Report a bug or request a feature"` | Welcome message displayed at the top of the form |
| `data-show-issue-link` | `"public"` | Show the GitHub issue link after submission: `"public"`, `"always"`, or `"never"` |
| `data-send-console-logs` | `"false"` | Start the "Send Console Logs" checkbox checked |

### Basic Example

Expand Down Expand Up @@ -110,6 +112,21 @@ Control whether the feedback form collects the submitter's name and email addres

When submitter information is collected, it is included in the GitHub Issue body so your team knows who reported the issue.

## Console Logs

BugDrop can include recent browser console output in the GitHub Issue. The feedback form shows a "Send Console Logs" checkbox. It is unchecked by default.

```html
<!-- Start with Send Console Logs checked -->
<script
src="https://bugdrop.neonwatty.workers.dev/widget.js"
data-repo="owner/repo"
data-send-console-logs="true"
></script>
```

When the checkbox is checked, the issue body includes a collapsed console-log section. BugDrop limits the amount of output and redacts obvious secret-like values such as passwords, tokens, cookies, authorization headers, and long random strings.

## Dismissible Button

Allow users to dismiss the floating button so it does not obstruct their view. This is especially useful for content-heavy sites where the button might overlay important elements.
Expand Down Expand Up @@ -199,6 +216,37 @@ Self-hosted deployments can also let pages set labels via the `data-category-lab

Only enable this when your worker's `ALLOWED_ORIGINS` is locked down to trusted domains.

## Auth Token Provider

Self-hosted deployments can require short-lived host-app auth tokens before BugDrop accepts feedback. This is useful when the widget is only meant for authenticated users in your product.

First, define a global function that fetches a token from your own backend:

```html
<script>
window.getBugDropToken = async function getBugDropToken() {
const response = await fetch('/api/bugdrop-token', { credentials: 'include' });
if (!response.ok) throw new Error('Unable to create BugDrop token');
const { token } = await response.json();
return token;
};
</script>
```

Then reference that function on the BugDrop script tag:

```html
<script
src="https://bugdrop.yourcompany.com/widget.js"
data-repo="owner/repo"
data-auth-token-provider="getBugDropToken"
></script>
```

The provider may return either a raw token or a value already prefixed with `Bearer `. BugDrop calls it before installation checks and feedback submissions, then sends the token in the `Authorization` header.

This attribute only adds the client-side header. Your self-hosted worker must also set `AUTH_TOKEN_SECRET` or `AUTH_TOKEN_ADDITIONAL_SECRETS` to enforce the token gate. One configured worker secret must be byte-for-byte identical to the host app's token-signing secret; if a valid-looking `bd1` token is rejected, check for trailing newlines or quoting differences. See the [Self-Hosting guide](https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md) for the worker environment variables, secret hygiene notes, and token claim format.

### Rules and behavior

- Recognized keys: `bug`, `feature`, `question`. Other keys are ignored with a warning.
Expand Down
7 changes: 3 additions & 4 deletions src/content/docs/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -208,16 +208,15 @@ If the widget appears but submissions fail:

1. **Check the GitHub App** -- Make sure it is installed on the correct repository with Issues and Contents permissions
2. **Check rate limits** -- You may have hit the per-IP or per-repository rate limit
3. **Check CSP** -- If your site uses a strict Content Security Policy, make sure `https://bugdrop.neonwatty.workers.dev` is allowed in `connect-src` so the browser can submit feedback to the Worker API
4. **Check the console** -- Look for error messages in the browser developer console
5. **Check the network tab** -- Inspect the API request to see the response status and body
3. **Check the console** -- Look for error messages in the browser developer console
4. **Check the network tab** -- Inspect the API request to see the response status and body

### Screenshots are not being uploaded

If issues are created but without screenshots:

1. **Check branch protection** -- The GitHub App needs permission to push to the `bugdrop-screenshots` branch. See the [Installation](/docs/installation) page for details on branch protection configuration.
2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script in `script-src` and feedback submission in `connect-src`.
2. **Check CSP** -- Make sure your Content Security Policy allows the BugDrop widget script.
3. **Cross-origin content** -- Browser screenshot rendering cannot capture cross-origin iframes or images loaded without CORS headers. These elements may appear blank in the screenshot.

### Can I use BugDrop on a static site?
Expand Down
8 changes: 3 additions & 5 deletions src/content/docs/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ BugDrop to visually cover in supported screenshot modes, mark those elements wit

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](/docs/security) on the Security page for details.
[Screenshot masking](/security#screenshot-masking) on the Security page for details.

## Step 3: You Are Done

Expand All @@ -111,12 +111,10 @@ The BugDrop script tag should **not** include the `async` or `defer` attributes.
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;
connect-src 'self' https://bugdrop.neonwatty.workers.dev;
Content-Security-Policy: script-src 'self' https://bugdrop.neonwatty.workers.dev;
```

`script-src` lets the widget load. `connect-src` lets the browser submit feedback to the BugDrop Worker API.
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

Expand Down
13 changes: 12 additions & 1 deletion src/content/docs/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,18 @@ If you run your own instance of BugDrop:
3. **Monitor your Cloudflare Worker logs** for unusual activity
4. **Add edge protections** such as WAF rules, CAPTCHA, bot detection, and allowlists as needed
5. **Define retention/cleanup** for the `bugdrop-screenshots` branch
6. **Keep your instance updated** with the latest version
6. **Use host-app auth tokens** when the widget should only be available to authenticated users
7. **Keep your instance updated** with the latest version

### Host-App Auth Tokens

For private or authenticated applications, self-hosted workers can require a signed token on feedback submissions. Set `AUTH_TOKEN_SECRET` on the BugDrop worker, mint short-lived tokens from your own backend after checking the user's session, and configure the widget with `data-auth-token-provider`.

When rotating secrets or sharing one worker across multiple authenticated host apps, keep the current `AUTH_TOKEN_SECRET` in place and add comma- or newline-separated verifier secrets with `AUTH_TOKEN_ADDITIONAL_SECRETS`. BugDrop accepts tokens signed by any configured secret, so one app can migrate without breaking another app that still signs with the primary secret.

This protects the feedback endpoint from direct API calls that bypass browser CORS. CORS still matters for browser isolation, but it is not an authentication boundary. The token should include the exact target repository and expire quickly, usually within 5 minutes.

If installation status is also sensitive, set `AUTH_TOKEN_REQUIRED_FOR_CHECK = "true"` so the widget's `/check/:owner/:repo` request requires the same token.

## Reporting Security Issues

Expand Down
Loading