Skip to article

Performance Guard

Grade every pull request against your main branch and block animation performance regressions before they merge.

Performance Guard stops you shipping animation performance regressions.

It audits every pull request, compares each page with your main branch, and posts the result as a comment and a required check. If a page gets worse than your policy allows, the check fails and the pull request can't merge.

Guard is part of Motion Cloud. Each person who opens pull requests needs a Motion Cloud seat, and Motion+ Team Annual seats count. Pull requests from people without a seat get a neutral check, so they never block a merge. Results are private to your organisation. Paid MotionScore plans include Guard too.

How it works

Guard has two halves:

  • The Motion GitHub App, installed on your organisation. It posts the comment and the check.
  • The Guard action (motiondivision/motionscore-guard@v2), which runs in your own GitHub Actions workflow. It audits your pages and sends the grades to Motion.

The action runs Chrome on your own runner, so audits are unmetered. Run it on as many pull requests as you like.

The action signs in with GitHub's OIDC token, so there's no API token to create, copy or rotate.

Setup

1. Install the Motion App

Open motion.dev/dashboard/guard. If you don't have Motion Cloud yet, the page links to the upgrade.

Click Install the Motion App on GitHub and pick the organisation (and repositories) to guard. GitHub asks you to authorise the App, which proves you can manage that installation, then sends you back to the dashboard. The dashboard lists the connected organisation. Your own GitHub account is connected at the same time.

2. Connect each author's GitHub account

Guard grades a pull request only when its author has a seat. Each person on your team opens motion.dev/dashboard/guard while signed in to the Motion account that holds their seat, and clicks Connect GitHub. GitHub confirms which account is theirs.

A GitHub account can be connected to one Motion account. Connecting it again from a different Motion account moves it.

Pull requests from bots, such as Dependabot and Renovate, use the seat of the person who installed the Motion App.

When an author has no seat, the check is neutral and says so. Guard doesn't grade or comment on that pull request.

3. Add the workflow

Add this file to your repository as .github/workflows/motion-guard.yml:

name: Motion Performance Guard
on:
  deployment_status:
  push:
    branches: [main]
permissions:
  id-token: write
  contents: read
jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      - uses: motiondivision/motionscore-guard@v2
        with:
          url: ${{ github.event_name == 'push' && 'https://example.com' || '' }}

Replace https://example.com with your production URL.

The workflow listens for two events:

  • deployment_status: Vercel, Cloudflare Pages and Netlify all tell GitHub when a preview deployment finishes. The action reads the preview URL from that event (which is why url is empty here) and audits the pull request.
  • push to main: the action audits your production URL. This builds the baseline, the grades every pull request is compared against. Without it, Guard has nothing to diff against.

Only a push, a schedule or a manual run on main can write a baseline. Deployments never do, and a production deployment with no open pull request is recorded but posts nothing.

id-token: write lets the action prove to Motion which repository and commit it's running for. It needs no other secrets.

Merge this workflow to main first. The first push records the baseline, and pull requests opened after that get a comment.

4. Make the check required

A failing check only blocks merging if you require it. In your repository, open Settings → Branches (or Rules → Rulesets), protect your default branch and add Motion Performance Guard as a required status check.

The pull request comment

Guard keeps one comment on each pull request and updates it in place on every push. It's deliberately quiet:

  • Only pages whose grade changed compared with main. If nothing moved, the comment says so in one line.
  • New findings on those pages, with the CSS selectors of the affected elements, so you can see exactly which animation caused the drop.
  • A fix prompt to paste into your coding agent. It describes each new finding and where it lives, so the agent can fix it without a round trip through the full report.

Policy

By default, the check fails when:

  • any page drops more than one grade (an A falling to a C, for instance), or
  • any page falls below C.

Change either rule with the action's inputs. Guard reads the policy from your main branch's workflow, so a pull request can't loosen its own gate by editing the file:

      - uses: motiondivision/motionscore-guard@v2
        with:
          url: ${{ github.event_name == 'push' && 'https://example.com' || '' }}
          floor: B
          max-drop: 0
  • floor: the lowest grade any page may have. Default C.
  • max-drop: how many grades a page may fall compared with main. Default 1. Set 0 to fail on any drop.

Waivers

Sometimes a regression is the right call. A new hero animation might be worth a grade.

Anyone with write access to the repository can waive a failing check in two ways:

  • Add the performance-ok label to the pull request.
  • Comment /guard accept on the pull request.

The check then passes as waived, and the dashboard records it as one. Once the pull request merges, the next push to main makes the new grades the baseline.

Which pages are audited

Guard picks pages from your sitemap automatically, so new pages are covered without touching the workflow. It audits the same pages on main and on pull requests, so the grades always compare like with like.

The dashboard

motion.dev/dashboard/guard shows every connected organisation and repository, the last run for each (with links to the pull request and the check), and a grade history for each page on main.

Other CIs

The GitHub App and its pull request comment are GitHub only. On any other CI, you can still gate builds with the MotionScore CLI. This needs a paid MotionScore plan:

npx motionscore https://preview.example.com --threshold A --token $MOTIONSCORE_TOKEN

Generate the token on the Motion dashboard.

  • Exit 0: threshold met.
  • Exit 1: the overall grade is below the threshold. Fail the build.
  • Exit 2: the audit could not run (configuration or infrastructure error).

--threshold is the lowest grade you'll allow through. It checks an absolute grade, not a change against main.

Add --summary result.json for a compact machine-readable result to post wherever your CI reports.

If api.motion.dev cannot be reached to verify your plan, the CLI warns and continues rather than failing your build. Pass --strict to fail instead.

Reliable grades in CI

MotionScore analyses performance from first principles, rather than measuring FPS.

FPS can fluctuate between environments and runs depending on load. MotionScore instead detects which elements are animating, how they animate, how they are triggered, which elements are layers, how big is the layer etc. Therefore, grades are more stable between runs and between environments.

The GitHub Action launches Chrome with --no-sandbox automatically: modern Ubuntu (23.10+, including GitHub's standard runners) blocks Chrome's sandbox for unprivileged processes, and on an ephemeral CI runner that flag is the standard answer. If you run the CLI in any other CI and the audit fails at launch with Failed to launch the browser process… No usable sandbox, set MOTIONSCORE_NO_SANDBOX=1 as an environment variable; the CLI suggests this itself when it hits that error.