Diffy

The Diffy channel asks the shipped GitHub Actions workflow to run a visual regression test against the newly deployed environment.

This page is for the lead or DevOps engineer who runs Diffy visual regression tests after deployments. It covers how the channel hands off to the workflow, the setup steps and every variable the channel reads.

The channel sends your repository a GitHub repository_dispatch event, and the test-vr.yml workflow does the rest. The workflow runs the Diffy comparison and posts the result back to the pull request. The channel itself never calls Diffy. The dispatch succeeds only when GitHub answers with HTTP 204, and any other status fails the channel.

Setup

To set up Diffy notifications:

1. Enable visual regression during installation, or ship test-vr.yml by hand. See Visual regression.
2. Add a GitHub token with repo scope as VORTEX_NOTIFY_DIFFY_TOKEN to the hosting environment (when it's unset, the channel uses VORTEX_NOTIFY_GITHUB_TOKEN, then GITHUB_TOKEN).
3. Add the repository, in owner/repo format, as VORTEX_NOTIFY_DIFFY_REPOSITORY to the hosting environment. When it's unset, the channel uses VORTEX_NOTIFY_GITHUB_REPOSITORY.
4. Add diffy to the comma-separated VORTEX_NOTIFY_CHANNELS list in your .env file, for example VORTEX_NOTIFY_CHANNELS=email,diffy. The installer leaves diffy out, even when you enable visual regression.

Confirm that the next deployment started a run. The deployment output on your hosting platform shows [ OK ] Finished Diffy notification. The repository's Actions tab lists a Test - Visual regression run.

Environment variables

See the Notifications overview for the router, what a failed channel stops, the shared VORTEX_NOTIFY_* variables and the Location column. The following table lists the variables that the Diffy channel reads:

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_DIFFY_TOKEN	Yes, unless VORTEX_NOTIFY_GITHUB_TOKEN or GITHUB_TOKEN is set	VORTEX_NOTIFY_GITHUB_TOKEN, then GITHUB_TOKEN	Hosting	GitHub token with repo scope used to call repository_dispatch
VORTEX_NOTIFY_DIFFY_REPOSITORY	Yes, unless VORTEX_NOTIFY_GITHUB_REPOSITORY is set	VORTEX_NOTIFY_GITHUB_REPOSITORY	Hosting	Repository in owner/repo format (an HTTPS repository URL works too)
VORTEX_NOTIFY_DIFFY_SOURCE_ENV	No	production	.env	Diffy source environment used as the baseline (production, staging, development)
VORTEX_NOTIFY_DIFFY_EVENT_TYPE	No	vr_run	.env	repository_dispatch event type the workflow listens for
VORTEX_NOTIFY_DIFFY_BRANCHES	No	None	.env	Exact branch names to dispatch for (comma-separated). When empty, every deployment dispatches and the workflow decides whether to compare
VORTEX_NOTIFY_DIFFY_BRANCH	No	VORTEX_NOTIFY_BRANCH	Hosting	Branch sent to the workflow and checked against VORTEX_NOTIFY_DIFFY_BRANCHES
VORTEX_NOTIFY_DIFFY_ENVIRONMENT_URL	No	VORTEX_NOTIFY_ENVIRONMENT_URL	Hosting	Deployed environment to compare against the source environment
VORTEX_NOTIFY_DIFFY_LABEL	No	VORTEX_NOTIFY_LABEL	Hosting	Diff name shown in the Diffy UI
VORTEX_NOTIFY_DIFFY_EVENT	No	VORTEX_NOTIFY_EVENT	Hosting	Deployment event; pre_deployment dispatches nothing

The workflow treats a deployment whose URL contains pr-<number> as a pull request deployment. By default, the workflow compares a pull request deployment when either the pull request carries the VR label or its head branch matches deps/*. It compares any other deployment only when its branch matches the VR_DIFFY_BRANCHES repository variable. Automatic on deployments covers these settings.

Event behavior

The channel skips pre_deployment, because the target environment isn't ready for comparison yet. Any other event, post_deployment included, dispatches the run.