> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Register your existing test suites

> Commit a manifest and retain exact candidate inventory bindings.

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.

```json theme={null}
{
  "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`](https://github.com/SynclyUS/bugspray/blob/main/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:

```sh theme={null}
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:

```sh theme={null}
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](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-registry.md) for bounds, retries and exact binding errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.