Two ways to use visualdiff

visualdiff reads a pull request and tells the reviewer what to read, what to skim and what can be skipped. You can sign up and let your code host call visualdiff on every push, or add one step to the CI you already run and use it without an account. Both produce the same review. They differ in where it runs, where the report is kept and who sets it up.

GitHub
GitLab
Bitbucket Cloud
Azure DevOps
Gitea / Forgejo

Sign up and connect your code host

Sign in, give visualdiff a token for your code host and add one webhook. From then on every push to a pull request is reviewed on visualdiff, and the result is posted back to the pull request.

One comment on the pull request, edited in place on every push
An optional commit status that fails on hold, for branch protection
Reports kept in your workspace, with share links and a review card
The sanity index, ArchCanvas infrastructure matching, and Slack or webhook alerts

Read the workspace guide Sign in

Use it inside your code host

Add one step to the CI job that runs on pull requests. A one-file CLI with no dependencies diffs the branch against its merge base, sends it for analysis and reports back where the pull request lives. No visualdiff account is needed.

The review in the job log, and in the job summary on GitHub Actions
The job fails on the verdict you choose, so it can be a required check
One comment on the pull request from GitHub Actions, using its own token
An API key is optional: add one to keep reports in a workspace

Read the CI guide

Which one fits

If both lists describe you, start inside your code host: it is one file, and connecting a workspace later only adds a key and a flag.

Sign up and connect when

You want every push reviewed without editing a pipeline in each repository.
You want reports kept, shared by link and tracked week by week in the sanity index.
You want Slack or your own endpoint told when a change is held.
You want changes matched to your running infrastructure through ArchCanvas.
Your code host is in the cloud, or a self-managed server is reachable from the internet over HTTPS.

Use it inside your code host when

You cannot, or do not yet want to, create an account for your team.
Your code host is on a private network. Only the CI runner needs to reach visualdiff, not the host.
You want the merge gate to be a CI job you already know how to require.
You want the change map to show which other files depend on the changed ones. The CLI builds the import graph from the whole checkout.

Side by side

What each way needs, where its results appear and what it costs. Statuses come from the roadmap.

Question	Sign up and connect	Inside your code host
What you need	A visualdiff sign-in. A token for each code host, with the scopes listed in the guide. Permission to add a webhook to the repository or organisation. A self-managed server must be reachable over public HTTPS.	A CI job that runs on pull requests and can run Node 18 or newer and git, with the target branch fetched. Outbound HTTPS from the runner to visualdiff.ai, or to your own deployment. No account; an API key is optional.
What starts a review	The code host calls visualdiff on every push to a pull request. Nothing changes in your pipelines.	Your pipeline runs the CLI as one step of a job on every pull request.
Where results show up	One comment on the pull request, edited in place on every push A commit status from visualdiff, if you turn it on, that can fail on hold Your visualdiff inbox and the report page Slack or your own endpoint, for held reviews or every review	The job log, and the job summary on GitHub Actions The job passes or fails on the verdict you choose with `--fail-on` One comment on the pull request from GitHub Actions; on other hosts, only with an API key and the host connected in a workspace
Where reports are stored	In your workspace on visualdiff. The newest 2,000 reports per workspace are kept.	Nowhere at visualdiff: the review lives in your CI logs and on the pull request. With an API key and `--store`, the report is also kept in your workspace.
Who can see them	Members of your workspace, by role. Anyone you give a report’s share link can open that one report without signing in.	Whoever can see the CI job and the pull request in your code host.
Setup	Sign in, save a token in Settings, test it, and paste the webhook URL and secret into the host. Once per host or organisation.	Add one CI file, or one step, to each repository. Add a secret if you use an API key.
Cost	Free during the beta. From general availability, private repositories, webhooks, statuses, ArchCanvas and the sanity index are in the Team plan at $15 per human reviewer per month. Agents and bots are never a seat.	Free during the beta. The pricing page lists the CI CLI and API keys in the Team plan from general availability.
Available today	GitHub, GitLab, Bitbucket Cloud, Azure DevOps, Gitea / Forgejo, including GitHub Enterprise Server, self-managed GitLab and Codeberg.	Any CI that can run a script. Recipes for GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines, and Gitea and Forgejo Actions.
On the roadmap	GitHub App on GitHub Marketplace: one-click install, no tokens Next Marketplace apps for GitLab, Bitbucket and Azure DevOps Planned Bitbucket Data Center and Gerrit adapters Next	Gitea / Forgejo action Planned MCP server, so agents review their own change first Next Native panels and check runs as the marketplace apps ship

Using both

The two ways combine. Run the CLI with an API key and --store, and the review shows in the pipeline and is kept in your workspace, where it counts towards the sanity index. If you also add a webhook to the same repository, let only one of them comment: both edit the same marked comment, so each run overwrites the other’s.

Try a review before setting anything up

Paste a public pull request link into the inbox, or open the sample: an agent-written pull request with six problems in 582 lines.

Open the inbox Open the sample review