Integrations

GitHub Actions

Run a full UX analysis on every pull request. The InterfaceGuard Action captures screenshots of your PR preview URL at desktop, tablet, and mobile viewports, runs AI-powered analysis, and posts the results as a PR comment — automatically.

What it does

Posts a UX analysis summary as a PR comment on every run
Works with any preview URL — Vercel, Netlify, Railway, and more
Desktop, tablet, and mobile viewport capture in one step
Optional quality gate: fail CI on critical or high-severity issues
Updates the existing comment on re-runs — no duplicate clutter
Links directly to the full report in the InterfaceGuard web app
Supports pre-captured screenshots as an alternative to a live URL
Available on Pro plan and above

Prerequisites

An InterfaceGuard account on the Pro plan or higher
An API key — generate one under Settings → API Keys
An InterfaceGuard project — create one under Projects and copy its ID
A PR preview deployment URL (e.g. from Vercel or Netlify) or pre-captured screenshots

Quick start

Store your API key as a secret

Never hard-code your InterfaceGuard API key in the workflow file. Add it as a repository secret named INTERFACEGUARD_API_KEY under Settings → Secrets and variables → Actions.

Add your API key as a repository secret

In your GitHub repository go to Settings → Secrets and variables → Actions → New repository secret. Name it INTERFACEGUARD_API_KEY and paste your API key as the value.

Create the workflow file

Add the following to .github/workflows/ux-review.yml. Replace your-project-id with your InterfaceGuard project ID and wire in your preview deployment URL.

The workflow uses pull_request_target so secrets are available for forked PRs, and skips Dependabot automatically. The action only needs a preview URL and API key — it does not check out PR code, so this is safe.

.github/workflows/ux-review.yml

name: UX Review

on:
  pull_request_target:
    branches: [main, develop]

jobs:
  ux-review:
    # Skip for Dependabot or other untrusted actors whose secrets are
    # unavailable. The action only needs a preview URL and API key — it
    # does not check out PR code, so pull_request_target is safe here.
    if: github.actor != 'dependabot[bot]' && github.actor != 'dependabot-preview[bot]'
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write   # required to post PR comments

    steps:
      - uses: cre8tivsystems/interfaceguard-action@v1
        with:
          api-key: ${{ secrets.INTERFACEGUARD_API_KEY }}
          project-id: your-project-id
          preview-url: ${{ steps.deploy.outputs.preview-url }}

Open a pull request

The action runs automatically. When analysis completes, InterfaceGuard posts a comment on the PR with severity counts, the top issues found, and a link to the full report.

Full example with Vercel preview deployments

This workflow deploys a Vercel preview on every PR, then passes the preview URL to InterfaceGuard. The fail-on-severity: critical setting fails the check if any critical UX issues are found.

.github/workflows/ux-review.yml

name: UX Review

on:
  pull_request_target:
    branches: [main]

jobs:
  deploy:
    # Skip for untrusted actors whose secrets are unavailable.
    if: github.actor != 'dependabot[bot]' && github.actor != 'dependabot-preview[bot]'
    runs-on: ubuntu-latest
    outputs:
      preview-url: ${{ steps.vercel.outputs.preview-url }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy preview
        id: vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

  ux-review:
    needs: deploy
    if: github.actor != 'dependabot[bot]' && github.actor != 'dependabot-preview[bot]'
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: cre8tivsystems/interfaceguard-action@v1
        with:
          api-key: ${{ secrets.INTERFACEGUARD_API_KEY }}
          project-id: your-project-id
          preview-url: ${{ needs.deploy.outputs.preview-url }}
          fail-on-severity: critical

Using pre-captured screenshots

If you already capture screenshots during your test run (e.g. with Playwright Test or Cypress), point the action at the output directory instead of a live URL.

- uses: cre8tivsystems/interfaceguard-action@v1
  with:
    api-key: ${{ secrets.INTERFACEGUARD_API_KEY }}
    project-id: your-project-id
    screenshots-dir: ./test-screenshots   # directory of PNG files
    analysis-types: accessibility,usability,visual-hierarchy

Action inputs

Input	Required	Default	Description
api-key	Yes	—	InterfaceGuard API key. Store as a GitHub Actions secret.
project-id	Yes	—	InterfaceGuard project ID. Find it under Projects in the web app.
preview-url	One of these	—	Live URL to capture — typically a Vercel, Netlify, or Railway preview.
screenshots-dir	One of these	—	Path to a directory of pre-captured PNG screenshots to upload directly.
analysis-types	No	accessibility, usability, consistency, visual-hierarchy	Comma-separated analysis types to run. See analysis types below.
fail-on-severity	No	none	Fail CI when issues at this severity or higher are found. Options: critical, high, none.
comment-on-pr	No	true	Post analysis results as a pull request comment.
poll-timeout-seconds	No	600	Maximum seconds to wait for analysis to complete.

Action outputs

Output	Description
job-id	InterfaceGuard job ID for the analysis that ran.
issues-count	Total number of UX issues found.
critical-count	Number of critical-severity issues found.
high-count	Number of high-severity issues found.
report-url	URL to the full analysis report in the web app.

Troubleshooting

Plan limit: URL-based analysis requires a Pro plan or higher.

Upgrade to the Pro plan at cloud.interfaceguard.com/pricing. All paid plans include the GitHub Actions integration.

Error: Either preview-url or screenshots-dir must be provided.

Make sure your workflow step that generates the preview URL runs before the InterfaceGuard action, and that the URL is passed via the preview-url input.

PR comment not posted (GITHUB_TOKEN not available).

Add permissions: pull-requests: write to your job in the workflow YAML. This is required for the action to post comments.

Timed out waiting for analysis job.

Increase poll-timeout-seconds (default 600). Long analyses may take several minutes depending on the number of viewports and analysis types selected.

API 401 Unauthorized.

Verify INTERFACEGUARD_API_KEY is set as a repository secret and the value matches the key in Settings → API Keys.

Ready to add UX quality gates to your CI?

Create a Pro account to get your API key and start catching UX issues before they merge.

Start Free Review All Integrations