Register your existing test suites

Start with working tests in your repository and a catalog product/workflow. Registration describes existing automation; it does not generate tests, install a runner or grant execution permission.

Add a manifest

Use .bugspray/suites.json. This synthetic example uses illustrative UUIDs: replace them with your actual authorized product and workflow IDs before using it with a real app.

{
  "schemaVersion": 1,
  "repository": "example/synthetic-app",
  "productId": "11111111-1111-4111-8111-111111111111",
  "suites": [{
    "id": "saved-view-roundtrip",
    "name": "Save and reopen a view",
    "description": "Checks saved filter persistence after reload; does not cover all view behavior.",
    "workflowIds": ["22222222-2222-4222-8222-222222222222"],
    "runner": {
      "provider": "github-actions",
      "workflow": ".github/workflows/e2e.yml",
      "job": "browser",
      "suite": "saved-view-roundtrip"
    },
    "fixtures": [],
    "environment": [{"service": "web", "revision": "candidate", "description": "Exact candidate frontend."}]
  }]
}

The strict v1 contract rejects unknown fields, duplicate IDs, traversal paths and oversized input. Limit JSON to 256 KiB and 100 suites. fixtures and environment are explicit requirements, not observed readiness. No credentials belong in a manifest. The complete contract lives in apps/shared/suite-registry.ts.

Import locally without a provider

The trusted-operator CLI can inspect an already available Git commit without fetching, checking it out or running tests. Commit the manifest in the target repository first. Run from the Bugspray checkout; set these values for your scratch repository:

export APP_CHECKOUT=/absolute/path/to/synthetic-app
export CANDIDATE="$(git -C "$APP_CHECKOUT" rev-parse HEAD)"
pnpm registry import \
  --db data/docs-suite-registry.sqlite \
  --workspace synthetic \
  --repository example/synthetic-app \
  --product 11111111-1111-4111-8111-111111111111 \
  --candidate "$CANDIDATE" \
  --manifest .bugspray/suites.json \
  --checkout "$APP_CHECKOUT"

The scratch repository’s origin must identify example/synthetic-app on GitHub. That local match is a provenance sanity check, not proof of remote access. Uncommitted files are ignored. Use a dedicated CLI database, separate from the app’s findings database and other worktrees. Retain the returned manifestDigest. Set MANIFEST_DIGEST to that exact SHA-256 value, then read:

pnpm registry read \
  --db data/docs-suite-registry.sqlite \
  --workspace synthetic \
  --repository example/synthetic-app \
  --product 11111111-1111-4111-8111-111111111111 \
  --candidate "$CANDIDATE" \
  --manifest .bugspray/suites.json \
  --digest "$MANIFEST_DIGEST" \
  --suite saved-view-roundtrip

A missing binding or unknown suite fails explicitly. There is no implicit “latest” substitution. CLI registration alone does not populate the app’s provider-owned candidate discovery list.

Enable authenticated candidate discovery

Connect/select your GitHub repository in Settings. Configure suite discovery for the authorized active product and manifest path; deployment defaults use BUGSPRAY_SUITE_PRODUCT_ID and optionally BUGSPRAY_SUITE_MANIFEST_PATH until an administrator saves discovery settings. Configure signed GitHub App deliveries to /api/integrations/github/webhook with the deployment’s secret. Relevant pull_request actions are opened, reopened, synchronize and ready_for_review, including drafts. The provider verifies the actual PR head and reads the exact candidate blob through scoped GitHub access. Ordinary branch pushes are not separate subscriptions. Enabling discovery does not backfill old PRs. Redeliver a relevant event or wait for the next update. Import creates no test execution, replay or check run. Refresh in Test suites reads status/freshness; it does not force an import. Hosted delivery reachability must be verified independently of App connection. A configured broker can forward signed deliveries for its explicitly bound installation/tenant over a service binding; the tenant still verifies the original signature. This is bounded routing, not general multi-tenant fan-out. See the registry operating contract for bounds, retries and exact binding errors.

Start here

Understand Bugspray

Use Bugspray

Register your existing test suites

Add a manifest

Import locally without a provider

Enable authenticated candidate discovery

​Add a manifest

​Import locally without a provider

​Enable authenticated candidate discovery

Add a manifest

Import locally without a provider

Enable authenticated candidate discovery