Docs

How Screenery works, one feature at a time.

Start here

• Getting started

  From zero to an embedded, self-updating screenshot: choose a setup path, push from CI, and paste one @latest URL into your README.

• GitHub Action

  Reference for screenery/push@v1: the workflow and permissions it needs, every input and output, fork pull requests, and pinning.

• Screenshot URLs

  The URL grammar, formats and caching, visibility levels, signed URLs, read tokens, and embedding.

Channels and promotion

• How @latest moves

  Channels, which builds move @latest, alerts for screenshots nobody pushes any more, promoting by hand, and which CI jobs may move the default branch.

• Promotion rules

  The default release and pull-request rules, tag prefixes for monorepos, the rule log, pruning, rollback and channel mode.

• Chat notifications

  Post to Slack, Discord or Microsoft Teams when a build changes screenshots or a channel is reviewed. Chat targets, conditions, Send a test, and why only public screenshots get a picture.

Testing and review

• Visual regression testing

  The optional visual-diff gate: compare each screenshot with a committed baseline, fail the job on a regression, and push nothing. Masks, and ignoring a flaky screenshot's known noise.

• Sharded test runs

  Push from a test run split across CI machines as shards of one snapshot, with one pull-request comment.

• Pull-request comments

  The preview comment on pull requests, the gallery and README Markdown each push writes, and verify-publish receipts.

• Reviewing screenshots

  Approve or reject each changed screenshot of a pull request with keyboard shortcuts, see its review state, hand the review to an AI agent, and require the screenery check before merge.

• Playwright and Argos

  Publish Playwright toHaveScreenshot goldens or an Argos upload folder as-is.

• Cypress

  Name each cy.screenshot(), keep failure screenshots out, and publish the rest.

• Vitest browser mode

  Keep toMatchScreenshot as the gate and publish its references from one folder.

• Storybook

  Capture every story with a short Playwright script and publish the PNGs.

Reference

• CLI reference

  Every command of the screenery CLI, with its flags, exit codes and environment variables.

• Credentials

  GitHub OIDC with no secret, SCREENERY_TOKEN, read and embed tokens, screenery login, and which credential each command uses.

• Docs plugins

  Write screenery: image references in Docusaurus or Starlight pages and get the @latest URL, with an optional dark version, when the site builds.

• AI agents

  Connect a coding agent over MCP, locally or through the hosted server, and let it set up a repository.

• Clips, evals and demos

  Capture live pages onto @clip, publish LLM UI evals onto @eval, and publish demo GIFs and videos.

• Monitoring live pages

  Clip your live site every day, compare each capture with the version you approved, get a chat message or an asset.changed webhook when it drifts, and approve drift by promoting it.