Percy "Error: Missing Percy token" (PERCY_TOKEN) in CI
The Percy CLI needs a write-scoped PERCY_TOKEN to associate the build with a project. If the variable is unset in the job, percy exec refuses to start and prints "Missing Percy token."
What this error means
A percy exec step exits immediately with "[percy] Error: Missing Percy token." No snapshots are uploaded and no build appears in the Percy dashboard.
[percy] Error: Missing Percy token
Error: Process completed with exit code 1.Common causes
PERCY_TOKEN not exposed to the step
The token is stored as a secret but not mapped into the environment of the step that runs percy exec, so the CLI sees nothing.
Secret unavailable on forked pull requests
Secrets are not passed to workflows triggered by forks, so PR runs from a fork have no token even though it is configured for the repo.
How to fix it
Map the token into the step env
Set PERCY_TOKEN from the repository secret on the step (or job) that runs Percy.
- run: npx percy exec -- npx playwright test
env:
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}Handle forked PRs explicitly
Run Percy on a trusted event so the token is available, or skip Percy when the token is absent.
- run: npx percy exec -- npx playwright test
if: ${{ env.PERCY_TOKEN != '' }}How to prevent it
- Store PERCY_TOKEN as a repository or organization secret.
- Map it into every step that runs
percy exec. - Plan for forked PRs, where secrets are not injected.