Multi-project setup
If you want to use Happo in multiple projects in your organization, you can do so with the project config option. You can have separate projects per repository, or even have separate projects within the same repository.
By default, Happo posts one build status per project:
Two Happo projects posting separate PR build statuses.
Combining projects
Since happo v6.23.0, you can have Happo combine every project that runs for the same commits into a single job, which posts a single Happo status check for all of them. Set group to true in the config of each project, and run them the way you normally would: each joins the job when it starts.
import { defineConfig } from 'happo';
export default defineConfig({
project: 'components',
group: true,
// ... rest of config
});
Two Happo projects posting a combined PR build status.
Changed in happo v7: group: true is the default, so projects combine without setting it. Set group: false to keep a project out of the combined job. See Upgrading to happo v7.
The status stays pending until every project that has started is done. Happo learns about a project only when it starts, though, so this is enough when your projects start at about the same time. If one starts later than the others (its CI job waits for another job, or installs browsers before it runs Happo), the others can finish first, and the job posts its status and pull request comment before the late project joins. When it joins, the status goes back to pending, and once it's done the job posts a new comment, which hides the first and names the projects that started late, as the job's page does. To have the job wait for every project from the start, also orchestrate: group and orchestration combine. Or give the late project a group of its own (see below), so it doesn't hold up the others' check.
Separate status checks with groups
Most teams need only one group. Some want a status check of their own for some projects: to make the component library a required check but not the end-to-end tests, say, or so that a project that runs later doesn't hold the others' check pending (more reasons). Give those projects a named group instead of true:
import { defineConfig } from 'happo';
export default defineConfig({
project: 'e2e',
group: 'e2e',
// ... rest of config
});
Each group gets its own status check: Happo for the default group (group: true), and Happo (e2e) for the projects in the e2e group. The groups still share one job, and its page lists the projects by group.
Pull requests without Happo runs
If Happo is a required status check and you only run it when some files change (using paths filters in GitHub Actions, for instance), a pull request that doesn't touch them never gets a Happo status, and can't be merged. Happo can't tell that a run isn't coming, so tell it, from the CI step that decides not to run Happo. Either:
- Skip the project: Happo posts a passing status on the commit, under the status check the project would have reported to. For a project with a
group, that's the group's check (HappoorHappo (e2e), say); otherwise it's the project's own. Skip once for each project, or each group, that doesn't run. - Or, if you use orchestration, orchestrate with no projects: Happo posts a passing
Happostatus for a job with nothing to check.
Skipping with the happo package
npx happo skip
It reads the project and group from your Happo config, like happo does, and posts for the current commit (--afterSha to name another). If a Happo run for the project, or for another project in its group, has already started on the commit, it posts nothing and leaves that run to post the status.
Skipping with curl
You don't need to check out your code or install anything to skip: one request to the skip endpoint does it. Here it is in GitHub Actions, as a job that runs when the one running Happo doesn't:
skip-happo:
needs: changes
if: needs.changes.outputs.ui != 'true'
runs-on: ubuntu-latest
steps:
- run: |
curl --fail-with-body --silent --show-error \
--retry 5 --retry-max-time 30 --max-time 10 \
-u "$HAPPO_API_KEY:$HAPPO_API_SECRET" \
--json '{"project": "components", "group": true, "ifNotStarted": true}' \
"https://happo.io/api/skip/$HEAD_SHA"
env:
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
HAPPO_API_KEY: ${{ secrets.HAPPO_API_KEY }}
HAPPO_API_SECRET: ${{ secrets.HAPPO_API_SECRET }}
HEAD_SHAis the full SHA of the pull request's head commit, the one your required check is on. Elsewhere,git rev-parse HEADin a checkout of the branch gives it.projectis the project's name in Happo. Leave it out for your account's default project.groupis what the project's config sets:true, a group's name, or leave it out for a project without a group.ifNotStartedmakes the call harmless if Happo does run for the commit: it then posts nothing, and answers{"posted": false}. Without it, a project that already has a Happo run is taken out of that run.--retrytries again, for up to 30 seconds, when happo.io answers with a server error or doesn't answer within 10 seconds (--max-time), so a brief outage doesn't fail the job. Skipping again is harmless.--jsonneeds curl 7.82 or later. With an older curl, use-H 'Content-Type: application/json' -d '{…}'instead.
Orchestrating with no projects
With orchestration, call the orchestrate endpoint with an empty list of projects instead of the list you'd otherwise run. Like the orchestrate call itself, it needs the merge base of the pull request, so check out its history first, but there's still nothing to install:
skip-happo:
needs: changes
if: needs.changes.outputs.ui != 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- run: |
before_sha=$(git merge-base "$BASE_SHA" "$HEAD_SHA")
curl --fail-with-body --silent --show-error \
--retry 5 --retry-max-time 30 --max-time 10 \
-u "$HAPPO_API_KEY:$HAPPO_API_SECRET" \
--json '{"projects": []}' \
"https://happo.io/api/jobs/$before_sha/$HEAD_SHA/orchestrate"
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
HAPPO_API_KEY: ${{ secrets.HAPPO_API_KEY }}
HAPPO_API_SECRET: ${{ secrets.HAPPO_API_SECRET }}
This posts the Happo status only. For a named group's Happo (<group>) status, skip instead.
Orchestration
With happo v6.23.0 and later, group combines projects without an orchestration call, which is enough when they start at about the same time. Orchestrate as well when a project starts later than the others: the orchestrated job knows every project from the start, so it doesn't post its status until all of them are done. Orchestration is also how to combine projects with older versions of the happo package, or if you call the Happo API without it.
If you know beforehand what projects you are going to run Happo for in CI, you can call the Orchestration API endpoint to tell Happo what projects you intend to process. Happo then combines them into one job, and posts one status for all of them.
Call the endpoint before any of the projects start running, with the same "before" and "after" commits that the happo command uses. For a pull request, that's the merge base of the PR's base branch and its head commit, and the head commit itself.
Orchestration with group
Orchestration and group (the default since happo v7) work together. A project with group that the orchestrate call listed joins the orchestrated job for its commits when it starts, and that job keeps posting its single Happo status. Two things to keep in mind:
- Orchestrate first. A project with
groupthat starts before the orchestrate call starts a combined job of its own, and the call then makes a second job beside it, which postsHappo. For a project in the default group (group: true), that's two jobs posting the same check. Have every project's CI job wait for the orchestrate call, as the jobs below do withneeds: orchestrate. - The orchestrated job posts one status. A project the call listed reports to
Happo, even if its config names a group. Leave a project with a named group out of the call, and it gets itsHappo (<group>)check from a combined job of its own.
Example
Here's an example GitHub Actions workflow with two projects: components, a Storybook configured in happo.config.ts, and e2e, a Playwright test suite configured in happo.e2e.config.ts. Pushes to main only create the reports that PRs are compared against, so there's nothing to orchestrate there.
name: Happo
on:
push:
branches: [main]
pull_request:
jobs:
orchestrate:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- run: |
before_sha=$(git merge-base "$BASE_SHA" "$HEAD_SHA")
jq -n --arg link "$PR_URL" --arg message "$PR_TITLE" '{
projects: ["components", "e2e"],
link: $link,
message: $message
}' | curl --fail-with-body --silent --show-error --json @- \
--retry 5 --retry-max-time 30 --max-time 10 \
-u "$HAPPO_API_KEY:$HAPPO_API_SECRET" \
"https://happo.io/api/jobs/$before_sha/$HEAD_SHA/orchestrate"
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
PR_URL: ${{ github.event.pull_request.html_url }}
PR_TITLE: ${{ github.event.pull_request.title }}
HAPPO_API_KEY: ${{ secrets.HAPPO_API_KEY }}
HAPPO_API_SECRET: ${{ secrets.HAPPO_API_SECRET }}
components:
needs: orchestrate
# Also run on pushes to main, where orchestrate is skipped.
if: ${{ !failure() && !cancelled() }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
fetch-depth: 0
- 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 }}
e2e:
needs: orchestrate
if: ${{ !failure() && !cancelled() }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
fetch-depth: 0
- uses: actions/setup-node@v4
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx happo --config happo.e2e.config.ts -- playwright test
env:
HAPPO_API_KEY: ${{ secrets.HAPPO_API_KEY }}
HAPPO_API_SECRET: ${{ secrets.HAPPO_API_SECRET }}
The project names in the orchestration call have to match the project option in each config file.
The --retry options matter here: the Happo jobs wait for orchestrate, so if the call fails, they don't run at all. With them, curl tries again for up to 30 seconds when happo.io answers with a server error or doesn't answer within 10 seconds. Orchestrating again is harmless, since the call finds the job it already made. If you read the answer of a request you retry (to pass it to jq, say), use --fail rather than --fail-with-body: with --fail-with-body, the body of a failed attempt comes before the answer of the one that worked.