How to Set Up Happo with GitHub Actions for an Indian Startup

To run Happo in GitHub Actions, install it in your frontend repository, configure the browser targets you need, save your Happo API key and secret as GitHub Actions secrets, and run npx happo on pull requests and pushes to your default branch. Run the default branch at least once first: Happo uses it as the comparison baseline for pull request reports.

The setup mechanics are the same for an Indian startup as for any other team. Happo’s reviewed documentation does not establish India-specific INR pricing, GST invoicing, data residency, or payment availability; confirm those terms with Happo before budgeting.

1. Choose the right Happo integration

Happo has a general configuration and CI workflow, plus integrations for Storybook, Playwright, and Cypress. Start with the guide for the framework that owns your UI snapshots. The generic CI setup below handles running Happo in GitHub Actions; it does not replace the dedicated Playwright or Cypress setup.

For a Storybook UI, follow Happo’s Storybook integration documentation. For Playwright or Cypress, use the corresponding integration guide linked from Happo’s documentation. Happo describes screenshot comparison across browser and viewport targets and optional accessibility regression checks.

2. Install Happo and configure targets

Install Happo as a development dependency with the package manager used by your repository:

# npm
npm install --save-dev happo

# pnpm
pnpm add --save-dev happo

# Yarn
yarn add --dev happo

Create a happo.config.ts in the repository root. Happo’s repository README shows a configuration using credentials from environment variables and browser target definitions. The exact target shape should follow the current README and any framework-specific integration you use; select only browsers your product needs and your plan supports.

import type { HappoConfig } from 'happo';

const config: HappoConfig = {
  apiKey: process.env.HAPPO_API_KEY,
  apiSecret: process.env.HAPPO_API_SECRET,
  targets: {
    chrome: {},
    firefox: {},
    'ios-safari': {},
  },
};

export default config;

Configuration APIs can evolve, so compare this illustrative target selection with the current Happo repository README before committing it. Keep secrets out of this file: read them from environment variables as shown.

3. Save credentials as GitHub Actions secrets

1. In your Happo account, obtain the API key and API secret.
2. In the GitHub repository, open Settings → Secrets and variables → Actions.
3. Create repository secrets named HAPPO_API_KEY and HAPPO_API_SECRET.
4. Pass those secrets to the Happo workflow step as environment variables. Do not commit the values into the workflow, config, or application source.

For a private repository that accepts pull requests from forks, GitHub does not expose repository secrets to those forked workflows. Plan for the Happo step to be skipped or unavailable for fork-originated pull requests; do not work around this by exposing credentials to untrusted code.

4. Add the GitHub Actions workflow

The following workflow follows Happo’s documented GitHub Actions structure. It checks out the pull request head when the event is a pull request, fetches enough history for comparison, fetches main as the baseline branch when needed, installs dependencies, and invokes the CLI.

name: Happo CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  happo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || github.ref }}
          fetch-depth: 100

      - name: Fetch main branch
        if: github.ref != 'refs/heads/main'
        run: git fetch origin main:main

      - uses: actions/setup-node@v4

      - name: Install dependencies
        run: npm ci

      - name: Run Happo
        run: npx happo
        env:
          HAPPO_API_KEY: ${{ secrets.HAPPO_API_KEY }}
          HAPPO_API_SECRET: ${{ secrets.HAPPO_API_SECRET }}

If your default branch is not main, replace main in the push filter and fetch step with its actual name, and set Happo’s documented base-branch option if your configuration requires one. Keep the pull request head checkout and baseline fetch consistent with that branch.

The sample uses npm and npm ci, which expects a committed lockfile. For pnpm or Yarn, configure the matching Node package-manager setup and frozen-lockfile install command. Pin or update GitHub Actions versions according to your repository’s dependency policy.

5. Create the first baseline and verify reports

1. Merge or push the workflow to the default branch and allow a Happo run to complete. That run creates the report used as the pull request baseline.
2. Open a pull request that changes a rendered component or page, and confirm a Happo report is produced and compared to the baseline.
3. Check the GitHub status or report link and confirm the intended browser targets appear.
4. Review expected visual changes before updating the baseline. A baseline should represent an intentional accepted UI state.

Happo’s unified CLI recognizes GitHub Actions, can select a pull request’s baseline, create a report for the current commit, compare reports, and post a status when permitted. Ensure the workflow has whatever GitHub permissions your repository policy requires for status reporting; Happo’s setup guide is the source of truth for the current permission details.

6. Estimate usage and plan fit

Happo defines one snapshot as one component variant in one browser. Estimate monthly demand as:

component variants × browser targets × Happo runs per month

For example, 40 component variants across two browsers on 30 runs per month is about 2,400 snapshots. Include reruns and all branches that execute the workflow when estimating actual use.

Published Happo plan	Monthly snapshot allowance	Browser coverage listed	Published price
Free	5,000	Chrome	Free
Starter	50,000	Chrome, Firefox	$149/month
Growth	150,000	Chrome, Firefox, Safari	$399/month
Pro	300,000	Chrome, Firefox, Safari, iOS Safari, Edge	$749/month

Happo lists additional snapshots at $0.006 each on these paid tiers and custom Enterprise pricing for 1M+ snapshots. These are the vendor’s published USD terms at research time; they are not an estimate of the final Indian rupee cost. The pricing page mentions credit card, ACH, or wire through Stripe, but the reviewed material does not establish which methods are available to an Indian startup or how GST and tax invoices are handled. Ask Happo to confirm currency conversion, taxes, payment access, invoice details, and any data residency requirements before selecting a paid plan. See Happo pricing.

7. Troubleshooting

Symptom	Likely cause	What to check
No comparison or missing baseline	The default branch has not completed a Happo run, or the pull request job cannot see its history.	Run the workflow on the default branch. Check the checkout depth and baseline fetch, and confirm the branch name is correct.
Authentication failure	A secret is missing, misspelled, or not available to that workflow event.	Verify both secret names and pass them as step environment variables. Fork-originated pull requests do not receive repository secrets.
Workflow fails at npm ci	The npm lockfile is missing or out of sync, or the project uses another package manager.	Commit the lockfile or switch to the repository’s package manager and its frozen-lockfile install command.
No expected browsers or snapshots	Targets are absent from the config, the integration is not connected, or the selected plan does not include the desired browser.	Check the configuration and integration guide, then compare target needs with the plan’s browser coverage.
Workflow cannot post a status	GitHub token permissions or repository policy prevent status updates.	Review workflow permissions and Happo’s current CI guidance for the status behavior you expect.
Unexpectedly high usage	Usage grows with variants, browser targets, and CI runs, including reruns.	Calculate variants × browsers × monthly runs and remove targets that do not serve a product requirement.

8. Reliability and performance considerations

• Keep a successful baseline run on the default branch so pull requests have a comparison point.
• Use enough Git history and explicitly fetch the baseline branch; shallow or mismatched checkouts can prevent comparisons.
• Choose browser coverage intentionally. Each additional browser multiplies snapshots and can increase the work in each run.
• Use lockfile-based dependency installation so CI installs the repository’s recorded versions consistently.
• Separate integration setup from the generic workflow for Playwright or Cypress, and follow their Happo-specific instructions.
• Review changes to the workflow and Happo configuration like other CI dependencies, especially action versions, credentials, and branch names.

Happo’s reviewed sources do not provide a benchmark for job duration or a guarantee of CI completion time, so measure runtime in your own repository before making a latency commitment to the team.

Or skip the browser setup

Happo is for visual regression testing of component variants across browsers. If your task is instead to capture a website screenshot or PDF by URL, ScreenshotNeo is the ScreenshotNeo option to consider: it returns an image or PDF from one API request and supports an MCP server for AI agents.

For example, request a WebP screenshot with cURL:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Equivalent Python and Node.js calls are available in the ScreenshotNeo API documentation:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, and failed loads are never billed, and cache hits cost nothing. Response headers report the page verdict and billing status.
• An MCP server gives Claude, Cursor, and other MCP clients tools to take screenshots, inspect page information, and capture PDFs.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month, with no card required.

FAQ

Does the setup change for an Indian startup?

The GitHub Actions workflow does not have an India-specific setup path in the reviewed Happo documentation. Billing and tax details for India need confirmation from Happo.

Can Happo run only on pull requests?

You can configure workflow triggers, but a baseline report must exist on the default branch for pull request comparisons. Keep a push run on that branch.

Is Happo a replacement for browser end-to-end tests?

It serves visual comparison and related regression checks. Use your existing integration’s dedicated Happo instructions where applicable, and retain functional tests for behavior that screenshot comparison does not verify.

Which Happo tier should a small startup choose?

Estimate monthly snapshots from variants, browsers, and runs, then compare that number and required browser coverage with Happo’s live plan limits. Confirm India billing terms before treating the USD list price as a budget.