Docs/Official Integration Guide

Qably Architecture & Telemetry Integration Guide

Learn how to connect your CI/CD test runners, ingest automated execution telemetry, and leverage Qably's AI-native test generator across your engineering organization.

1. Monorepo Architecture

Qably is engineered as a pnpm + Turborepo workspace, built with strict boundary isolation and shared TypeScript domain contracts:

apps/web: Next.js 16 (App Router), React 19, Better Auth, Zustand, and Tailwind CSS v4 dashboard.
apps/api: NestJS 11 enterprise backend with Prisma ORM, PostgreSQL, Fastify engine, and BullMQ background workers.
packages/types: Shared domain interfaces (ProjectSummary, Run, AiCase, Suite).
apps/landing: Blazing fast marketing site built with Astro 7 and selective React 19 islands.

2. Authentication & API Keys (`apps/api`)

All CI/CD runners authenticate against Qably's API using project-scoped tokens prefixed with qbly_live_*.

# Required HTTP Header on every API request

Authorization: Bearer qbly_live_8f2a1c4d9e6b4a2f

You can create, inspect, and revoke tokens anytime from Settings > API Keys in the web dashboard.

3. CI Run Ingestion (`POST /runs/ingest`)

The POST /runs/ingest endpoint in apps/api processes pipeline telemetry with sub-second response times:

POST /runs/ingest
Content-Type: application/json
Authorization: Bearer qbly_live_8f2a1c4d9e6b4a2f

{
  "projectId": "proj-1",
  "suiteId": "suite-e2e-checkout",
  "source": "github_actions",
  "commitSha": "7a8b9c0d12e",
  "branch": "main",
  "cases": [
    {
      "name": "User completes checkout with credit card",
      "status": "pass",
      "durationMs": 1420
    },
    {
      "name": "User enters expired promotional coupon",
      "status": "fail",
      "durationMs": 850,
      "error": "CouponExpiredError: Code SUMMER26 has expired"
    }
  ]
}

4. GitHub Actions CI Integration

Drop the following configuration into .github/workflows/qably-quality-gate.yml:

name: Qably Quality Gate
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - name: Install dependencies
        run: pnpm install
      - name: Run Tests with Qably Telemetry
        run: pnpm test --reporter=@qably/reporter
        env:
          QABLY_TOKEN: ${{ secrets.QABLY_TOKEN }}
          QABLY_PROJECT_ID: ${{ vars.QABLY_PROJECT_ID }}

5. AI Test Case Extraction & Review Inbox

Qably's AI agent parses code AST and PR diffs deterministically, identifying edge cases, concurrency hazards, and missing validation assertions:

1. Deterministic Proposals: High-confidence assertions tailored to your testing framework (Playwright, Jest).

2. Human Review Gate: Proposals land in your team's Review Inbox, where QA leads review and approve diffs before merging.

3. Traceability Graph: Approved tests link bidirectionally to requirements and live dashboard health scores.

6. Local Development Environment (`apps/api`)

To run the backend API server locally:

# 1. Start PostgreSQL container
docker compose up -d

# 2. Run Prisma schema migrations
pnpm --filter @qably/api prisma migrate dev

# 3. Start development server with Fastify
pnpm --filter @qably/api run start:dev