Bug Beaconby Airship Labs
Theme

Install Bug Beacon

Get from sign-in to your first delivered report in a few steps. Reporters do not need a Bug Beacon or GitHub account.

1. Sign in and create an application

Sign in with GitHub, then choose Add application. Give your app a name and list the exact HTTPS origins that may embed the report button (one per line, including the port if you use one).

2. Connect a GitHub Project

On the application settings page, open GitHub connection. Paste your GitHub Project URL and a personal access token. Bug Beacon encrypts the token on the server and never sends it to the browser widget.

  • Personal Projects need a classic token with the project scope.
  • Organization Projects usually need a fine-grained token with organization Projects write permission. Your organization may require approval.

Manage GitHub tokens on GitHub when you create or rotate a token.

3. Add the Report Bug widget

Copy the snippet from your application settings, or install the open-source browser SDK the same way.

Script tag (registers the custom element automatically):

<script src="https://bugbeacon.ai/widget/v1.js" defer></script>
<bug-beacon project-id="YOUR_PUBLIC_PROJECT_ID" endpoint="https://bugbeacon.ai"></bug-beacon>

Replace YOUR_PUBLIC_PROJECT_ID with the public project ID shown in the dashboard. The ID is public and is not a credential.

npm (Node.js 24 or later):

npm install @bugbeacon/browser

import { defineBugBeacon } from "@bugbeacon/browser";

defineBugBeacon();

Then render the same <bug-beacon> element in your HTML. Call defineBugBeacon() in the browser; the ESM entry does not register the element during server rendering.

More options and configuration details live in the browser SDK repository.

4. Send a test report

Load a page on an allowed origin, click Report Bug, and submit a short title and description. In the dashboard, check Latest delivery on your application settings. When GitHub confirms delivery, the status shows Delivered and a new draft item appears in your connected Project.

If delivery fails or stays uncertain, fix the GitHub connection before retrying so you do not create duplicate items.

Need help?

Email support@airshiplabs.com.