Skip to content
Vizzly Docs

GitHub Integration

Starter Plan Required

Connect your GitHub repositories to get automated status checks on pull requests and automatic baseline selection using your git history.

What It Does

Status checks on commits. Every build creates a GitHub check run that shows pass/fail status. Visual changes block merges until someone approves them.

Baseline selection from git. Vizzly uses GitHub’s compare API to find where your branch diverged and automatically selects the right baseline build.

PR comments with visual diffs. Build summaries with screenshots and diffs post directly to your pull requests (optional).

Setup

  1. Install the GitHub App

    Go to your organization settings, find the GitHub integration section, and click to install the app. GitHub will ask which repositories you want to grant access to.

  2. Link a repository to your project

    In project settings, select the GitHub repository. This tells Vizzly which builds should get status checks.

You can start with one repository and expand access later from your GitHub app installation settings.

Status Checks

When CI runs visual tests and uploads screenshots, Vizzly creates a check run on the commit. The check updates as comparisons complete:

  • Success - Build approved, safe to merge
  • Action Required - Visual changes need review
  • Failure - Build rejected or tests failed

The check title shows what happened. Examples: “Visual Tests Approved”, “3 Visual Differences Detected”, “Test Command Failed”. Click Details to view the build.

When Checks Show Success vs Action Required

Builds show “Action Required” until explicitly approved. Even if all screenshots match perfectly, the check stays in action required state until someone approves the build.

This prevents accidental auto-merges. If you want certain changes to auto-approve (like small pixel differences), configure auto-approval rules in project settings.

Baseline Selection

When GitHub is connected, Vizzly uses git mode for baseline selection. It calls GitHub’s compare commits API to find the merge base between your branch and the baseline branch (usually main).

For pull requests, it compares against the PR’s base branch. For regular branch builds, it finds where your branch diverged from the configured baseline branch.

If no build exists at the merge base commit, Vizzly falls back to the latest approved build on the baseline branch.

You can override this by switching to manual baseline mode in project settings.

PR Comments

Enable PR comments in project settings to post build summaries on pull requests. Choose what to include:

  • None - No comments posted
  • New Screenshots - Embed new screenshot images
  • Diffs - Embed visual diff images

Each build posts its own comment. If a new build runs for the same commit, Vizzly updates the existing comment instead of creating duplicates.

Troubleshooting

Status checks not appearing

Your CI needs to pass the commit SHA to Vizzly. The SDK usually detects this from environment variables like GITHUB_SHA or CI_COMMIT_SHA.

If checks still don’t appear:

  1. Verify the repository is linked in project settings
  2. Check the GitHub App has permission for that repository
  3. Look at the build metadata for GitHub API errors
Repository not in project settings dropdown
  1. Check the GitHub App is installed for that repository
  2. Make sure the repository isn’t archived
  3. Verify you have admin access in both GitHub and Vizzly
  4. Use the refresh button in the repository dropdown
Check runs on wrong commits

This happens when the commit SHA from CI doesn’t match the PR’s head SHA. Common causes:

  • CI using merge commit SHA instead of head commit SHA
  • Tests running after GitHub rebases the PR
  • Workflow triggered on wrong branch

Check your CI logs for the commit SHA being passed to Vizzly. It should match the PR’s head commit.

Baseline selection not working

Git mode baseline selection needs:

  • Repository linked to the project
  • GitHub App permission to access the repository
  • Commit SHA exists in the remote repository

If the commit doesn’t exist remotely yet (like in local testing), Vizzly falls back to the latest approved build on the baseline branch.

You can pass common_ancestor_sha from your CI if you’ve already calculated the merge base locally.

Next Steps