Visual testing on open source repos and fork pull requests

Open source repos get many of their pull requests from forks, and GitHub withholds your secrets from a fork's workflow run. The usual one-job setup (capture, then uiverify upload with UIVERIFY_API_KEY) therefore captures fine on a fork PR but has no key to upload with. The fix is two workflows: the first captures with no secrets, the second uploads that capture with your key and never runs anything from the pull request. Pushes and pull requests from your own branches keep working exactly as before.

GitHub never passes repository secrets to a workflow triggered by a pull_request event from a fork, even after a maintainer approves the run. It gets only a read-only token, so a stranger's pull request cannot read your API key. This is a GitHub security rule, not a UI Verify limit: every tool that uploads with a secret hits the same wall. Adding the secret to the fork does not help either, because the run executes in your repo and reads only your repo's secrets.

1. Your visual workflow runs on pull_request and push as usual. For a push or a pull request from your own branches it uploads in the same job, with your key. For a pull request from a fork it saves the capture as a build artifact instead.
2. A second workflow, triggered by workflow_run when the first one succeeds, downloads that artifact and uploads it for the pull request's own commit, branch and number. GitHub always runs this workflow from your default branch's copy, with your secrets, so a pull request cannot change what it does.
3. UI Verify posts its UI Verify: <slug> status on the pull request's commit, and accepting the changes turns it green, the same as for any other pull request.

Start from your quickstart workflow and add two conditions: upload only when the run is not from a fork, and save the capture as an artifact when it is. Replace the capture step with yours: build Storybook into storybook-static, or run your Vitest or Playwright tests, which write uiverify-archive.

Dependabot opens its pull requests from a branch in your own repo, so the visual workflow treats them as yours and uploads in the same job. GitHub gives a workflow triggered by Dependabot only the secrets stored for Dependabot, not your Actions secrets, so UIVERIFY_API_KEY is empty and the upload fails with UIVERIFY_API_KEY is required. Add the same key under Settings, Secrets and variables, Dependabot. The check is worth keeping on these pull requests: a dependency bump is one of the most common ways a UI changes without anyone touching your code.

Add this file as is. The workflows: name must match the name: of the visual workflow above. It downloads the capture, fetches the pull request's commits as git objects (the CLI reads them to find the right baseline) without checking out a single file, and runs a pinned CLI from an empty directory.

A repo with more than one visual suite, such as component tests and docs pages that each upload to their own UI Verify project, needs only one upload workflow. List every capture workflow under workflows: and pick the key by the name of the run that finished. Each capture workflow keeps saving its artifact as uiverify-archive; the download step reads it from the run that triggered the upload (run-id), so the suites never mix.

A workflow_run run is recorded against your default branch, not the pull request, so it never shows as a job on the PR. That is why it passes --exit-zero-on-changes. On a fork's pull request the gate is the UI Verify: <slug> status, which flips green the moment the changes are accepted. Make it a required status check; for your own branches, keep the job gate and the auto-rerun workflow if you prefer it. Both are in Make the visual check required.

Keep GitHub's approval gate on too: in the repo settings, under Actions, require approval for workflows from outside collaborators, so a maintainer clicks Approve and run before a first-time contributor's capture runs at all.

• The job that runs the contributor's code (the capture) has no secrets.
• The job that holds the key runs none of the contributor's code: it never checks out the pull request, never runs npm ci, and never runs npx inside the pull request's tree, where an edited .npmrc or package.json could swap the CLI for something else.
• The CLI version is pinned and runs from an empty directory, and it only reads the downloaded capture plus git objects.
• Values the pull request controls, like its branch name, reach the shell through env, never through ${{ }} inside a script, where a crafted branch name could inject a command.
• A pull request that edits either workflow changes nothing that runs with the key: GitHub runs workflow_run from your default branch's copy.

pull_request_target also runs your default branch's workflow file with secrets for a fork's pull request, and it is the setup many guides suggest. To capture the pull request's UI, though, it has to check out and run the contributor's code: install scripts, .npmrc, the test config and the tests themselves. Doing that in a job that holds your key lets a malicious pull request read it, which GitHub Security Lab calls a pwn request. Splitting it into two jobs helps, but the capture job still runs a stranger's code with your repo's privileges: outside-contributor approval does not apply to pull_request_target, the token can write unless you restrict it, and the job shares the Actions cache with your default branch. With pull_request plus workflow_run, GitHub sandboxes the untrusted half for you.

If your build pulls packages from a private registry, a fork's pull request cannot install them, so no visual check can capture it in GitHub Actions, with or without this setup. Run the visual tests in the CI that already holds the registry token and upload from there; the CLI reads the commit, branch and pull request from COMMIT_SHA, BRANCH and PR_NUMBER on any CI. Whether that pipeline should build outside contributions is your call, since it means running their code next to the token.

The capture job installs a browser, and npx playwright install --with-deps shells out to apt-get for Chromium's system libraries. On GitHub's Ubuntu runners that apt call regularly hangs, on a slow mirror or an apt lock, with no timeout - the job runs until the global limit. Install only the browser you capture with (chromium), or run the job inside Microsoft's Playwright image, where Chromium and its system libraries are pre-baked, so there is no apt at all.

Inside a container the checked-out repo is owned by a different user than the job runs as, so git refuses to run in it and prints fatal: detected dubious ownership. The upload reads the commit and branch for the build, so it fails. Add the config git itself suggests, right after checkout:

A fork contributor cannot reach a private staging backend - no VPN, no secrets - so a test that renders live data will flake for them and for you as the data drifts. Freeze the data in the test instead: intercept the API with committed fixtures, or drive the components in Storybook, so every capture replays identical content regardless of where it runs. See Fix flaky visual tests.