How to Connect Happo to GitHub Actions

Happo supports GitHub Actions. Add a YAML workflow under .github/workflows, install your project dependencies, and run npx happo with HAPPO_API_KEY and HAPPO_API_SECRET supplied as GitHub secrets. Happo’s maintained Continuous Integration guide provides this GitHub Actions recipe; its CLI detects GitHub Actions, creates a report, compares it with a baseline, and can post a status to the pull request.

This guide covers the standard Happo CLI integration. If your screenshots are captured through Happo’s Cypress or Playwright integrations, Happo says to follow the separate integration-specific CI instructions linked from its CI guide.

1. Add Happo to your project

Happo’s current package is happo. Add it as a development dependency using the package manager already used by your project:

npm install happo --save-dev

pnpm add happo --save-dev

yarn add happo --dev

Commit the resulting manifest and lockfile so the workflow can install the same dependency versions as local development. The maintained Happo repository shows npm install happo --save-dev and npx happo as package and CLI examples. See the Happo repository for package-level configuration context.

2. Configure Happo credentials

Happo uses the environment variables HAPPO_API_KEY and HAPPO_API_SECRET. Add values for both as GitHub Actions secrets, then reference them in the workflow environment for the Happo step. Do not commit API credentials in the YAML file or repository.

The official GitHub Actions example uses the expressions ${{ secrets.HAPPO_API_KEY }} and ${{ secrets.HAPPO_API_SECRET }}. The example below follows Happo’s maintained workflow, including checkout of the pull request head, fetching the default branch, dependency installation, and the Happo CLI.

3. Create the GitHub Actions workflow

Create .github/workflows/happo.yml. GitHub discovers workflow files in .github/workflows; a workflow is YAML made up of triggers, jobs, and steps. The workflow below is Happo’s documented GitHub Actions setup for a repository whose default branch is named main.

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

      - run: npm ci

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

Reference: Happo’s maintained CI instructions. GitHub’s overview of workflow files and components is in its Understanding GitHub Actions documentation.

Adapt the workflow to your repository

Default branch: Happo’s documented example uses main. Replace main in both the push trigger and fetch command if your default branch has another name. Happo’s guide says its command assumes a main baseline.
Package manager: The example uses npm ci, which expects a committed npm lockfile. Use your project’s corresponding locked install command if it uses pnpm or Yarn.
Node setup: The Happo example includes actions/setup-node@v4 without a Node version input. Follow your project’s Node version policy if it requires a pinned version; keep this choice aligned with the project runtime.
Pull request and baseline runs: The documented triggers run Happo on pull requests and pushes to main. The default-branch run gives PR comparisons a baseline report.
Workflow filename: You can choose another filename as long as it ends in .yml or .yaml and lives under .github/workflows.

4. Store the secrets in GitHub

Open the repository’s GitHub settings and navigate to Actions secrets.
Create a secret named HAPPO_API_KEY and paste the corresponding Happo credential.
Create a secret named HAPPO_API_SECRET and paste the corresponding Happo credential.
Commit the workflow and push it. Confirm the run starts from the Actions tab.

GitHub’s general documentation covers using secrets in GitHub Actions. The secret names above are the ones Happo documents for this workflow.

5. Understand the baseline and pull request status

Happo’s unified CLI detects GitHub Actions and assumes a pull-request model. Its documented flow finds the baseline starting from the pull request’s merge base, creates a report for the current HEAD, compares the reports, and posts a status if configured and permitted.

Run the workflow on pushes to the default branch as well as on pull requests. Happo specifically recommends default-branch pushes so PR builds have a baseline to compare against. If the baseline branch is not main, use your actual default branch consistently in the trigger and fetch step.

For GitHub status updates, the maintained guide says to install the Happo GitHub App and connect the repository through Happo’s GitHub integration page. If you cannot install the app, Happo documents an alternate pull request comment using --githubToken and the Actions-provided GITHUB_TOKEN:

- run: npx happo --githubToken ${{ secrets.GITHUB_TOKEN }}

This token option is an alternative described by Happo for posting a status as a pull request comment. Follow GitHub’s current token permissions guidance for your repository and workflow. GitHub Enterprise Server has separate Happo instructions; Happo notes that its standard GitHub App steps apply to github.com or Happo’s on-premise service, not self-hosted GitHub Enterprise Server.

Optional configuration

Happo project configuration

The current Happo repository shows a happo.config.ts example that reads the API credentials from environment variables and defines browser targets. Treat that as package-level configuration context: tailor targets and screenshot setup to your app. The CI workflow itself can remain the maintained Happo recipe above.

import { defineConfig } from 'happo';

export default defineConfig({
  apiKey: process.env.HAPPO_API_KEY!,
  apiSecret: process.env.HAPPO_API_SECRET!,
  targets: {
    'chrome-desktop': {
      type: 'chrome',
      viewport: '1280x720',
    },
  },
});

Consult the current Happo repository and Happo’s configuration documentation for the configuration formats and target options supported by your installed version.

Pull request notifications

Happo’s CI guide documents the optional --notify CLI argument for email notifications when comparison reports are ready. A fixed recipient can be supplied as follows:

npx happo --notify dev-team@example.com

To notify the commit author’s email in a GitHub Actions run, Happo shows this form:

npx happo --notify $(git show -s --format=%ae HEAD)

Happo also supports comma-separated addresses. Choose recipients and notification behavior according to your team’s needs; this option is separate from the workflow required to run comparisons.

Troubleshooting

Symptom	Likely cause	What to check
No Happo workflow appears in Actions	The file is outside the discovery directory or has the wrong extension.	Put it in `.github/workflows` and use a `.yml` or `.yaml` filename.
Authentication fails	A secret is missing, misspelled, or unavailable in the run context.	Confirm the exact names `HAPPO_API_KEY` and `HAPPO_API_SECRET` in GitHub settings and in the step environment. Ensure values are not accidentally surrounded by extra quote characters.
Dependency installation fails	The workflow install command does not match the project’s package manager or lockfile.	Use the package manager and committed lockfile that the repository uses. For npm, `npm ci` requires a lockfile consistent with `package.json`.
Happo cannot find or compare against a baseline	The default branch has not run successfully, or the workflow still fetches `main` while the project uses another default branch.	Enable push runs for the actual default branch and update the fetch step to that branch. Check the workflow logs and Happo comparison report.
Pull request status is missing	The Happo GitHub App is not installed or the repository is not connected in Happo, or the app cannot be used in this environment.	Follow Happo’s GitHub status steps. If app installation is unavailable, review Happo’s documented `--githubToken` comment alternative and GitHub token permissions.
Workflow uses an unexpected commit	The checkout reference differs from the PR head or current ref.	Keep the documented `github.event.pull_request.head.sha \|\| github.ref` reference unless your workflow intentionally uses a different commit model.
Wrong base branch is compared	The default branch differs from Happo’s assumed `main` branch.	Update the push trigger and fetch step consistently. If using another Happo CLI integration or custom CI model, consult Happo’s maintained guide for its applicable base-branch option.

Performance, reliability, and cost considerations

The example uses a fresh GitHub-hosted runner, installs dependencies, fetches branch history, and runs the Happo CLI. Build time therefore depends on your dependency installation and screenshot suite. The guide does not provide a benchmark or a guaranteed run time. Start with the documented workflow, then use the Actions logs to identify the slow step before changing checkout depth or adding dependency caching.

Keep the default-branch baseline run enabled: pull request comparisons need a report to compare with. If a workflow is skipped, credentials are absent, or the base branch is not fetched, the run may not produce the comparison you expect. Happo’s pricing and plan details can change; consult Happo directly for current account costs. This guide makes no claim about a specific plan, quota, or price.

Or skip the browser setup

If the job you need is to capture a website screenshot or PDF, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return PNG, JPEG, WebP, or PDF. For example, this cURL call saves a WebP screenshot:

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

See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

FAQ

Does Happo support GitHub Actions?

Yes. Happo lists GitHub Actions as a supported CI environment and documents a workflow using the happo CLI.

Does this workflow capture screenshots by itself?

The workflow runs Happo’s configured suite. Your project still needs the Happo configuration and screenshot setup appropriate to its integration.

Should I use the older happo.io package?

No. The current repository identifies the integration library as the happo npm package. Use Happo’s maintained docs and current package instructions.

Can I use this standard CLI recipe with Cypress or Playwright?

Happo’s CI guide explicitly directs Cypress and Playwright users to the separate integration-specific CI instructions.