GitHub Actions Integration

GoDiffy provides a powerful GitHub Action that fully automates visual regression testing in your CI/CD pipeline. Unlike other solutions, you don't need to write screenshot capture code—GoDiffy handles everything: screenshot capture, upload, comparison, and reporting.

No Screenshot Code Required

Just provide a config file with your URLs, and GoDiffy automatically:

🎯 Captures screenshots from your deployed applications
📤 Uploads them to secure cloud storage
🔍 Compares them against your baseline
📊 Generates detailed reports
💬 Posts results as PR comments

You focus on your app, we handle the visual testing.

Traditional Approach vs. GoDiffy

❌ Traditional Approach ✅ GoDiffy Approach

❌ Traditional Approach	✅ GoDiffy Approach
`# Install browser automation - name: Setup Playwright run: npx playwright install # Write screenshot code - name: Take screenshots run: \| node scripts/capture-screenshots.js # Upload to storage - name: Upload to S3 run: \| aws s3 sync ./screenshots s3://... # Write comparison logic - name: Compare images run: \| node scripts/compare-images.js # Generate reports - name: Create report run: \| node scripts/generate-report.js`	`# That's it! 🎉 - name: Visual regression test uses: GoDiffy/godiffy-github-actions@v1 with: api-key: ${{ secrets.GODIFFY_API_KEY }} site-id: ${{ secrets.GODIFFY_SITE_ID }} capture-screenshots: true config-path: './godiffy.json'`

# Install browser automation
- name: Setup Playwright
  run: npx playwright install

# Write screenshot code
- name: Take screenshots
  run: |
    node scripts/capture-screenshots.js
    
# Upload to storage
- name: Upload to S3
  run: |
    aws s3 sync ./screenshots s3://...
    
# Write comparison logic
- name: Compare images
  run: |
    node scripts/compare-images.js
    
# Generate reports
- name: Create report
  run: |
    node scripts/generate-report.js

# That's it! 🎉
- name: Visual regression test
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    capture-screenshots: true
    config-path: './godiffy.json'

Quick Start

1. Get Your API Credentials

Sign up for GoDiffy if you haven't already
Create a site for your project in the GoDiffy dashboard
Generate an API key in your account settings
Copy your site ID from the site settings

2. Add GitHub Secrets

Add your GoDiffy credentials as repository secrets:

Go to Settings → Secrets and variables → Actions
Add these secrets:
- GODIFFY_API_KEY: Your GoDiffy API key
- GODIFFY_SITE_ID: Your site ID (optional, can be in config file)

3. Create Configuration File

Create godiffy.json in your repository root:

godiffy.json
{
  "siteId": "your-site-id",
  "baseUrls": {
    "master": "https://your-app-production.com",
    "dev": "https://your-app-dev.com"
  },
  "pages": [
    {
      "name": "home",
      "path": "/"
    },
    {
      "name": "features",
      "path": "/features"
    },
    {
      "name": "pricing",
      "path": "/pricing"
    }
  ],
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "threshold": 0.95,
  "algorithm": "pixelmatch"
}

4. Create Workflow

Create .github/workflows/visual-regression.yml:

That's it! No need to install Playwright, write screenshot code, or manage storage. GoDiffy handles everything automatically.

.github/workflows/visual-regression.yml
name: Visual Regression Testing

on:
  push:
  pull_request:

jobs:
  upload-screenshots:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Capture and upload screenshots
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: true
        config-path: './godiffy.json'
        create-report: false

  compare-screenshots:
    if: github.event_name == 'pull_request' || github.ref != 'refs/heads/master'
    needs: upload-screenshots
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Wait for uploads to process
      run: sleep 5

    - name: Run visual regression comparison
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: false
        config-path: './godiffy.json'
        baseline-branch: ${{ github.base_ref }}
        baseline-commit: latest
        create-report: true
        post-pr-comment: true
        github-token: ${{ secrets.GITHUB_TOKEN }}

What Just Happened?

Notice there's no screenshot capture code in this workflow!

The capture-screenshots: true parameter tells GoDiffy to:

Launch a headless browser
Navigate to each URL in your godiffy.json
Capture full-page screenshots
Upload them to secure cloud storage
Compare against your baseline

All automatically. You just provide the URLs and configuration.

Configuration Reference

Action Inputs

Input	Required	Description	Default
`api-key`	✅	Your GoDiffy API key	-
`site-id`	✅	Your site ID	-
`config-path`	✅	Path to godiffy.json config file	`./godiffy.json`
`capture-screenshots`	❌	Whether to capture screenshots	`true`
`images-path`	❌	Path to pre-captured screenshots	-
`create-report`	❌	Whether to create a comparison report	`true`
`baseline-branch`	❌	Branch to compare against	`master`
`baseline-commit`	❌	Specific commit or "latest"	`latest`
`threshold`	❌	Similarity threshold (0-1)	From config file
`algorithm`	❌	Comparison algorithm	From config file
`post-pr-comment`	❌	Automatically post PR comment with results	`false`
`github-token`	❌	GitHub token for PR comments	`secrets.GITHUB_TOKEN`

Action Outputs

Output	Description
`total-comparisons`	Total number of comparisons performed
`passed-comparisons`	Number of comparisons that passed
`failed-comparisons`	Number of comparisons that failed
`average-similarity`	Average similarity percentage (0-100)
`threshold-met`	Whether threshold was met (true/false)
`report-id`	ID of the generated report
`report-url`	URL to view the report

Configuration File (godiffy.json)

{
  "siteId": "your-site-id",
  "baseUrls": {
    "master": "https://production-url.com",
    "dev": "https://dev-url.com",
    "staging": "https://staging-url.com"
  },
  "pages": [
    {
      "name": "home",
      "path": "/"
    },
    {
      "name": "about",
      "path": "/about"
    }
  ],
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "threshold": 0.95,
  "algorithm": "pixelmatch"
}

Configuration Options:

siteId: Your GoDiffy site identifier
baseUrls: URLs for different branches/environments
pages: Array of pages to screenshot
- name: Identifier for the screenshot file
- path: URL path to capture
viewport: Browser viewport dimensions
- width: Viewport width in pixels
- height: Viewport height in pixels
threshold: Similarity threshold (0-1, where 1 = identical)
algorithm: Comparison algorithm (pixelmatch, ssim, mse)

Usage Patterns

Basic Screenshot Capture

Capture screenshots from your deployed application:

- name: Capture screenshots
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    capture-screenshots: true
    config-path: './godiffy.json'

Upload Pre-Captured Screenshots

If you already have screenshots from your test suite:

- name: Upload existing screenshots
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    capture-screenshots: false
    images-path: './screenshots'
    config-path: './godiffy.json'

Run Comparison

Compare current branch against baseline:

- name: Compare screenshots
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    capture-screenshots: false
    baseline-branch: master
    baseline-commit: latest
    create-report: true
    config-path: './godiffy.json'

Custom Threshold

Override the threshold from config:

- name: Compare with custom threshold
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    threshold: 0.92
    algorithm: ssim

Pull Request Integration

Automatic PR Comments

Enable automatic PR comments by setting post-pr-comment: true:

- name: Compare screenshots
  uses: GoDiffy/godiffy-github-actions@v1
  with:
    api-key: ${{ secrets.GODIFFY_API_KEY }}
    site-id: ${{ secrets.GODIFFY_SITE_ID }}
    create-report: true
    post-pr-comment: true
    github-token: ${{ secrets.GITHUB_TOKEN }}

That's all you need! The action will automatically:

Find the PR number (works for both pull_request and push events)
Fetch the comparison report from the API
Post a formatted comment with results
Fail the workflow if threshold not met

Example Comment:

## ❌ Visual Regression Report - FAILED

**Results:** 0/4 comparisons passed
**Average Similarity:** 46.13%
**Threshold:** 95%

⚠️ **Visual changes detected that exceed the acceptable threshold**

⚠️ 4 comparison(s) below individual threshold

**🔗 [View Full Report](https://godiffy-backend.up.railway.app/sites/.../reports/...)**

---
*Generated by GoDiffy GitHub Action*

No Custom Code Required

Unlike other solutions, you don't need to write any github-script code or manage API calls. Just set post-pr-comment: true and the action handles everything.

Status Checks

The action integrates with GitHub's status check system:

✅ Success: All comparisons pass the threshold
❌ Failure: Comparisons fall below threshold
The workflow will fail if threshold-met is false

Branch Protection

Require visual regression checks before merging:

Go to Settings → Branches
Edit your branch protection rule
Enable "Require status checks to pass before merging"
Select "compare-screenshots" from the list

Complete Examples

Full Two-Job Workflow

name: Visual Regression Testing

on:
  push:
  pull_request:

jobs:
  upload-screenshots:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Capture and upload screenshots
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: true
        config-path: './godiffy.json'
        create-report: false

  compare-screenshots:
    if: github.event_name == 'pull_request' || github.ref != 'refs/heads/master'
    needs: upload-screenshots
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Wait for processing
      run: sleep 5
    
    - name: Compare screenshots
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: false
        baseline-branch: ${{ github.base_ref }}
        baseline-commit: latest
        create-report: true
        post-pr-comment: true
        github-token: ${{ secrets.GITHUB_TOKEN }}
        config-path: './godiffy.json'

Single Job Workflow

name: Visual Testing

on:
  pull_request:

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Run visual regression test
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: true
        create-report: true
        config-path: './godiffy.json'

With Custom Test Suite

name: E2E + Visual Testing

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run E2E tests (generates screenshots)
      run: npm run test:e2e
    
    - name: Upload screenshots to GoDiffy
      uses: GoDiffy/godiffy-github-actions@v1
      with:
        api-key: ${{ secrets.GODIFFY_API_KEY }}
        site-id: ${{ secrets.GODIFFY_SITE_ID }}
        capture-screenshots: false
        images-path: './test-results/screenshots'
        create-report: true

Best Practices

1. Consistent Screenshots

Use fixed viewport sizes
Wait for animations to complete
Mock or freeze dynamic content (dates, random data)
Ensure fonts are fully loaded

2. Threshold Selection

0.95-0.99: Strict, catches small changes
0.90-0.95: Moderate, allows minor differences
0.85-0.90: Lenient, only catches major changes

3. Performance Optimization

Capture screenshots in parallel when possible
Use images-path to upload pre-captured screenshots
Limit the number of pages to essential ones
Use appropriate viewport sizes

4. Workflow Organization

Separate upload and compare jobs for better control
Use continue-on-error: true to ensure PR comments post
Add appropriate permissions for PR comments
Use if conditions to control when comparisons run

Troubleshooting

Screenshots Not Uploading

Problem: Screenshots aren't appearing in GoDiffy

Solutions:

Verify API key and site ID are correct
Check that capture-screenshots: true is set
Ensure URLs in godiffy.json are accessible
Review workflow logs for error messages

Comparisons Always Pass

Problem: Comparisons show 100% similarity despite changes

Solutions:

Ensure baseline images exist on the master branch
Check that different URLs are configured for different branches
Verify the comparison is using the correct commits
Wait a few seconds between upload and compare jobs

PR Comments Not Posting

Problem: No comment appears on pull requests

Solutions:

Add pull-requests: write permission to the job
Ensure the PR comment script is included in your workflow
Check that GODIFFY_API_KEY secret is set
Verify the report was created successfully

Flaky Tests

Problem: Comparisons fail inconsistently

Solutions:

Add wait times for React/Vue hydration (await page.waitForTimeout(2000))
Use waitUntil: 'networkidle' in Playwright
Mock dynamic content (timestamps, random IDs)
Increase threshold slightly (e.g., 0.95 → 0.93)

Action Version Issues

Problem: Action behavior changes unexpectedly

Solutions:

Pin to a specific version: @v1.0.0 instead of @v1
Review the changelog
Test in a separate branch before updating

Demo Repository

See a complete working example:

🔗 godiffy-github-demo

This demo repository shows:

Complete workflow configuration
PR with visual regression failures
Automatic PR comments
Screenshot capture from deployed apps
Threshold-based pass/fail logic

Resources

Action Repository - Source code and releases
Demo Repository - Working example
API Documentation - Backend API reference
Features Guide - Platform capabilities

Getting Help

If you need assistance:

Check the demo repository for working examples
Review workflow logs for error messages
Open an issue on GitHub
Contact support at support@godiffy.app

Next Steps:

Explore Features to learn about advanced capabilities
Review API Documentation for custom integrations
Learn Visual Regression Concepts to understand best practices

No Screenshot Code Required​

Traditional Approach vs. GoDiffy​

Quick Start​

1. Get Your API Credentials​

2. Add GitHub Secrets​

3. Create Configuration File​

4. Create Workflow​

Configuration Reference​

Action Inputs​

Action Outputs​

Configuration File (godiffy.json)​

Usage Patterns​

Basic Screenshot Capture​

Upload Pre-Captured Screenshots​

Run Comparison​

Custom Threshold​

Pull Request Integration​

Automatic PR Comments​

Status Checks​

Branch Protection​

Complete Examples​

Full Two-Job Workflow​

Single Job Workflow​

With Custom Test Suite​

Best Practices​

1. Consistent Screenshots​

2. Threshold Selection​

3. Performance Optimization​

4. Workflow Organization​

Troubleshooting​

Screenshots Not Uploading​

Comparisons Always Pass​

PR Comments Not Posting​

Flaky Tests​

Action Version Issues​

Demo Repository​

Resources​

Getting Help​

No Screenshot Code Required

Traditional Approach vs. GoDiffy

Quick Start

1. Get Your API Credentials

2. Add GitHub Secrets

3. Create Configuration File

4. Create Workflow

Configuration Reference

Action Inputs

Action Outputs

Configuration File (godiffy.json)

Usage Patterns

Basic Screenshot Capture

Upload Pre-Captured Screenshots

Run Comparison

Custom Threshold

Pull Request Integration

Automatic PR Comments

Status Checks

Branch Protection

Complete Examples

Full Two-Job Workflow

Single Job Workflow

With Custom Test Suite

Best Practices

1. Consistent Screenshots

2. Threshold Selection

3. Performance Optimization

4. Workflow Organization

Troubleshooting

Screenshots Not Uploading

Comparisons Always Pass

PR Comments Not Posting

Flaky Tests

Action Version Issues

Demo Repository

Resources

Getting Help