Use BugCapsule

Using BugCapsule with Sentry

Keep Sentry where you track errors and issues. BugCapsule records the replayable Capsule for the same failure, links the Sentry event and the Capsule, and shows the reproduction and verification result on the Sentry issue. You don't move your workflow.

What it does, and what it doesn't

1. Add the companion to your app

import * as Sentry from '@sentry/browser';
import { BugCapsule, sentryCompanion, networkIntegration, historyIntegration } from '@bugcapsule/web';

Sentry.init({
  dsn: '<your Sentry DSN>',
  integrations: [sentryCompanion()],   // add to your existing integrations
});

await BugCapsule.init({
  appVersion: '1.4.0',
  appBuild: '52',
  mode: 'qa',
  monitoring: false,                   // Sentry stays your error monitor
  gitSha: import.meta.env.VITE_BUGCAPSULE_GIT_SHA,
  token: 'bcsdk.v1.…',                 // SDK token from the dashboard
  integrations: [networkIntegration(), historyIntegration()],
});

• The order of the two init calls doesn't matter: one thrown error gives one Sentry event and at most one Capsule, whichever handler sees it first.
• monitoring: false turns off BugCapsule's own error events, sessions and tracing headers; capture and replay keep working.
• Errors you report with Sentry.captureException(err) are linked too. Call BugCapsule.reportError(err) as well if you want the failure to reproduce in replay builds that don't load Sentry.

What the bugcapsule.capture tag means

2. Connect Sentry in the dashboard

A project owner or admin does this once per project. For the pilot the connection uses a Sentry internal integration in your own organization:

1. In Sentry: Settings → Developer Settings → Custom Integrations → Create New Integration → Internal Integration.
2. Permissions: Project Read; Issue & Event Read & Write; Organization Read. Turn on Alert Rule Action.
3. Save, then copy the token and the Client Secret.
4. In BugCapsule: your project → Integrations → Sentry: choose the region (sentry.io, us.sentry.io or de.sentry.io), enter the organization, project and integration slugs, the token and the Client Secret, and connect. BugCapsule checks them with Sentry before saving and keeps them encrypted.
5. Copy the webhook URL BugCapsule shows into the integration's Webhook URL in Sentry.
6. Create an alert rule for the Sentry project with the action Send a notification via your integration. (Organizations on Business or Enterprise plans can also subscribe the integration to error events.)

The Integrations page shows the status (Connected, Needs attention, Access revoked), the last delivery, and any failed deliveries with a Retry button. A Sentry project can be connected to one BugCapsule project only.

3. Work from either side

• In Sentry: the issue shows a BugCapsule#… link with the latest outcome. Open it (sign in to BugCapsule) to see each event and its Capsule.
• In BugCapsule: a Capsule page shows In Sentry links to its event and issue. The Sentry issue page lists every event BugCapsule saw, with its Capsule, or No capsule recorded and the reason.
• Replay and verify as usual (bugcapsule CLI). Each recorded run updates the link on the Sentry issue: REPRODUCED, STILL FAILING, INCONCLUSIVE, COULD NOT RUN or FIXED (only when every requested attempt ran validly and none reproduced).

Disconnecting

Disconnect from the Integrations page. BugCapsule deletes the stored token and secret, stops processing, and can first remove its links from Sentry issues. Then delete or rotate the integration's token in Sentry. Uninstalling the integration in Sentry also stops BugCapsule at once.

Troubleshooting