Quickstart

Get a QualityGate result on your next GitHub pull request in about ten minutes.

This guide takes a GitHub repository from nothing to a QualityGate comment on a pull request. You need a site that deploys a preview for each pull request (Vercel, Netlify, Render, Cloudflare Pages, or your own pipeline). If you do not have previews, see Build and serve in the same job.

Using GitLab or Bitbucket? Follow GitLab CI or Bitbucket Pipelines instead.

1. Create your organization

Open app.qualitygate.dev and create an account. Verify your email address from the link we send you.
Go to Organizations and create an organization for your team or agency. You become its owner.

2. Connect your repository

Go to Projects and choose Connect GitHub. GitHub asks you to install the QualityGate GitHub App: pick Only select repositories and choose the repositories you want to scan. Back in QualityGate, select one under Select a repository and fill in Allowed domains.

Allowed domains are the hostnames QualityGate may scan for this project. Enter hosts only, without https:// or a path. A leading *. allows any subdomain:

*.preview.example.com
staging.example.com

A scan of any other host is refused, so a leaked configuration cannot be pointed at someone else’s site. See Preview deployments for the right value for your host.

3. Add the workflow

Create .github/workflows/qualitygate.yml. Replace the url with the preview address of the pull request. The example below uses a predictable Netlify deploy preview address; other hosts are covered in Preview deployments.

name: QualityGate

on:
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - name: Install the scanning browser
        run: npx -y playwright@1.61.1 install --with-deps chromium

      - name: Scan the preview
        uses: qualitygate/scan-action@v1
        with:
          url: https://deploy-preview-${{ github.event.pull_request.number }}--your-site.netlify.app

That is the whole integration. Because the repository is connected through the GitHub App, the workflow needs no secret: id-token: write lets GitHub sign a short-lived token that proves which repository is asking.

Why install a browser? QualityGate scans in your CI runner with a real Chromium, the same one Playwright uses. The QualityGate Action v1 scans with Playwright 1.61.1, so install that version.

4. Open a pull request

Push a branch and open a pull request. The action waits up to two minutes for the preview to respond, scans it, and posts a comment like this one:

❌ QualityGate needs attention
Accessibility · a11y

1 critical issue (max 0); 1 serious issue (max 0)

Severity   Found  Limit  Status
Critical       1      0    ❌
Serious        1      0    ❌
Moderate       1      -    ℹ️
Minor          0      -    ℹ️

Monthly usage  18 / 100 runs

Prioritized issues
- [critical] image-alt       img.hero
- [serious]  color-contrast  .pricing .muted
- [moderate] region          .banner

The check fails when the counts exceed the limits, which by default means any critical or serious finding. The same report is written to the job summary, and every run is recorded under the project’s history in the app.

5. Make it required

In GitHub, open Settings → Branches → Branch protection rules for your main branch, enable Require status checks to pass, and select the QualityGate job (quality in the example above). Pull requests with a failing gate can no longer be merged.

Next steps

Your site already has issues and you only want to block new ones? Turn on regression mode.
Check more than accessibility with a different bundle.
Scan several pages or sites from one workflow: Multiple pages and sites.
Invite your team and set up notifications in Organizations and projects.
Compare scan capacity and projects in Pricing and packages.
Queue a public HTTPS scan without a CI job: Cloud scans.

Local scans

The repository includes a local CLI using the same scan engine. It is not currently a published npm package. If you have a QualityGate source checkout, install its workspace dependencies and build the scan packages:

pnpm install --frozen-lockfile
pnpm --filter @qualitygate/shared build
pnpm --filter @qualitygate/core build
pnpm --filter @qualitygate/cli build
pnpm --filter @qualitygate/core exec playwright install chromium
node packages/cli/dist/bin.js scan https://your-preview.example.com --bundle a11y

Use --format json for machine-readable output or --bundle full for the combined core scan. The local CLI supports eight browser-only bundles; geo and seo-deep require backend analysis and run through CI or Cloud. Local CLI runs do not upload results or consume account quota, and they do not establish an authorized CI gate or stored baseline. Run node packages/cli/dist/bin.js --help for options and exit codes.