GitHub Actions

Add the generated workflow and keep pull requests and baselines in sync.

Guided setup#

1. Open the project's Setup page as an owner or admin.
2. Copy the upload token and save it in GitHub under Settings → Secrets and variables → Actions, named FRAMECHECK_TOKEN.
3. Confirm that the secret is saved, then choose Open pull request.
4. Review the proposed .github/workflows/framecheck.yml, including the install command, Node version, Storybook command, and build directory.
5. Let the setup pull request run, review its images, and merge it.

If GitHub asks an organisation owner to approve new App permissions, complete that approval before retrying. Framecheck needs permission to open the setup pull request; installing the App does not store your upload token in GitHub for you.

What the workflow must do#

• Test the pull request's own head commit, rather than accidentally labelling a merge commit as the head.
• Run on pull requests and on pushes to your baseline branch.
• Determine the merge base for pull requests.
• Run the precheck before building to respect project skip rules.
• Build static Storybook and upload the output with the project token.

The generated workflow handles these steps. Use it as the starting point for monorepos and custom build pipelines.

Build tools and monorepos#

Check the detected package manager and lockfile, workspace directory, build command, and output path. The uploader path is relative to the directory where the upload command runs. If a job changes the Node version to build Storybook, it must still run the uploader with Node 24.

For Vite-based Storybooks, keep --stats-json in the build command for Smart Snapshots. The file must be included in the uploaded output.

Forks and Dependabot#

Fork pull requests do not receive repository secrets. The generated workflow skips them. Do not work around this by running untrusted pull-request code with repository secrets under pull_request_target.

Dependabot uses separate Dependabot secrets. Save FRAMECHECK_TOKEN there too if those pull requests should be tested, or configure a skip rule. A missing token on an ordinary pull request is an error to fix, not a visual pass.

Updating a generated workflow#

Setup can regenerate an unchanged generated workflow on its setup branch. It will not silently overwrite a customised workflow. Compare the new suggestion with your version, preserve necessary custom steps, and keep the uploader URL and checksum together.

Require the check before merging#

Once a run has posted its check, add the appropriate Framecheck check to your GitHub branch protection or ruleset. Choose Require visual approval if reviewers should be able to approve intentional differences. Framecheck's policy and GitHub's required-check rule serve different purposes; configure both.