Performance Guard stops you shipping animation performance regressions.
It audits every pull request, compares your selected pages with the main branch, and posts the results. If a page gets worse than your policy allows, the check fails. Once you make the check required, the pull request can't merge.
Guard is included with Motion Cloud. Guard grades a pull request when its author has a Motion Cloud seat. Other pull requests get a neutral check. Results are private to your organisation.
Setup
1. Install the Motion Performance app
Open the Performance Guard dashboard.
Click Install on GitHub and pick the organisation (and repositories) to guard. This also connects your GitHub account to your Motion account. Each teammate who opens pull requests connects their own GitHub account on the same page.
Pull requests from bots, such as Dependabot, use the seat of the person who installed the Motion Performance app.
2. Add the workflow
Add this file to your repository as .github/workflows/motion-guard.yml:
name: Motion Performance Guard
on:
deployment_status:
permissions:
id-token: write
contents: read
jobs:
guard:
runs-on: ubuntu-latest
steps:
- uses: motiondivision/motionscore-guard@v2
with:
pages: |
/
/pricingMost hosts, such as Vercel and Netlify, tell GitHub when a deployment finishes, and Guard audits that deployment's URL:
- A preview deployment of a pull request is checked against the baseline.
- A production deployment of main updates the baseline.
- The first run on a repo, even a pull request, saves the starting baseline.
Deploy from your own CI? Run Guard after your deploy step and pass url:.
Audits run on your own runner, so they are unlimited. id-token: write lets GitHub vouch for the run, so there is no API token to create.
3. 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.
Reports
Guard posts its report as one comment on each pull request, and updates it on every new deployment:
- Only pages whose grade changed or that fail the policy 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:
floor: B
max-drop: 0Options
| Input | Default | What it does |
|---|---|---|
pages | / | Paths to audit, one per line. |
floor | C | Lowest grade any page may have, or none for no floor. |
max-drop | 1 | How many grades a page may fall compared with main. Set 0 to fail on any drop. |
serve | none | A command that builds and serves the site on the runner, for repos without preview deployments. For example npm run build && npx serve dist -l 4173. Use it with url, for example http://localhost:4173. |
url | the deployment's URL | Set this only when you deploy from your own CI, or serve the site on the runner. |
cli-version | the tested version | The motionscore CLI version. The default is the version this release was tested with. |
Outputs, for later steps in your workflow: verdict (for example pass, fail or skipped) and check-url.
Skip
Sometimes you'll want to skip a check, because you accept the performance cost of a particular animation.
Anyone with write access to the repository can skip a failing check in two ways:
- Add the
performance-oklabel to the pull request. - Comment
/guard accepton the pull request.
The check then passes as skipped. Once the pull request merges, the next production deployment of main makes the new grades the baseline.
Which pages are audited
List the pages with your key animations under pages:. Guard audits the same list on main and on pull requests, so the grades compare like with like. With no pages:, Guard audits / only.
Dashboard
The Performance Guard dashboard shows all connected organisations and repositories, the status of the last run, and the grade history for each page.
Consistency
Performance Guard uses the MotionScore grading system to analyse 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 and how big each layer is. So grades are more stable between runs and between environments.