Docs

Quick start

Paste a pull request link into the inbox. Public repositories need nothing else. For a private repository, add a token for its host in Settings, or paste the output of git diff origin/main...HEAD instead of a link.

The report opens on the review plan: the hunks to read closely, to skim and to skip, in reading order, inside the time budget at the top. The other tabs answer one question each: where the change sits (map), what looks wrong (findings), whether it does what it says (intent), who wrote it (provenance), what it tests and imports, and which running resources it reaches.

CI recipes

The CLI is one file with no dependencies. It diffs HEAD against the merge base with the target branch, reads the base tree, manifests and .visualdiff.json from the base revision, builds an import graph from the checkout, and posts it all to the API. It prints the review, writes it to the GitHub job summary, and exits 1 on the verdict you pass to --fail-on. Run node visualdiff.mjs --help for every option, or --dry-run to see what would be sent.

Create a key with the write scope in Settings and store it as VISUALDIFF_KEY. Without a key the review still runs; it is printed, not stored. If you would rather not download the script on every run, commit it to your repository.

GitHub Actions

name: visualdiff
on: pull_request
permissions:
  contents: read
  pull-requests: write      # to post the review comment
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # the merge base must be reachable
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: curl -fsSL https://visualdiff.ai/cli/visualdiff.mjs -o "$RUNNER_TEMP/visualdiff.mjs"
      - run: node "$RUNNER_TEMP/visualdiff.mjs" --comment --store --fail-on hold
        env:
          VISUALDIFF_KEY: ${{ secrets.VISUALDIFF_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

visualdiff:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    GIT_DEPTH: "0"
  script:
    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - curl -fsSL https://visualdiff.ai/cli/visualdiff.mjs -o /tmp/visualdiff.mjs
    - node /tmp/visualdiff.mjs --store --comment --fail-on hold
  # VISUALDIFF_KEY: a masked CI/CD variable. --comment posts through your
  # workspace's GitLab connection (Settings → Code hosts).

Bitbucket Pipelines

pipelines:
  pull-requests:
    '**':
      - step:
          name: visualdiff
          image: node:22
          clone:
            depth: full
          script:
            - git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
            - curl -fsSL https://visualdiff.ai/cli/visualdiff.mjs -o /tmp/visualdiff.mjs
            - node /tmp/visualdiff.mjs --store --comment --fail-on hold
# VISUALDIFF_KEY: a secured repository variable.

Azure Pipelines

pr:
  branches:
    include: [main]
pool:
  vmImage: ubuntu-latest
steps:
  - checkout: self
    fetchDepth: 0
  - task: NodeTool@0
    inputs:
      versionSpec: '22.x'
  - script: |
      curl -fsSL https://visualdiff.ai/cli/visualdiff.mjs -o "$(Agent.TempDirectory)/visualdiff.mjs"
      node "$(Agent.TempDirectory)/visualdiff.mjs" --store --comment --fail-on hold
    env:
      VISUALDIFF_KEY: $(VISUALDIFF_KEY)

Jenkins, Buildkite, CircleCI, Drone and Woodpecker work the same way: check out with full history, then run the CLI with --base origin/<target>.

Webhooks

With a webhook, every push to a pull request is reviewed without CI: visualdiff fetches the change, stores the report, edits its one comment in place and, if you turn it on, sets a status that fails on hold. Add the host in Settings → Code hosts with a token; the page shows a webhook URL and secret once.

Tokens

• GitHub: Fine-grained token: Pull requests (read & write to comment), Contents (read), Commit statuses (read & write for status checks).
• GitLab: Project or group access token with read_api (api to post notes and statuses), role Reporter or above.
• Bitbucket Cloud: Repository access token with Pull requests: Write and Repositories: Read; or an Atlassian API token with your email as the username.
• Azure DevOps: Personal access token with Code (Read), plus Code (Status) and Pull Request Threads (Read & write) to report back.
• Gitea / Forgejo: Access token with read:repository (write:issue to comment, write:repository for statuses).

Policy

Commit .visualdiff.json to the default branch. It is read from the base revision of each pull request, so a change cannot loosen the rules it is judged by. Without one, the workspace policy from Settings applies, and without that the defaults. Keys you leave out keep their defaults. A blocking violation turns the verdict to hold; a warning adds a reason.

{
  "maxChurn": 1200,
  "maxChurnAI": 400,
  "maxFiles": 60,
  "requireTestsFor": ["src/**", "app/**"],
  "protected": [
    { "path": "**/auth/**", "reason": "Security reviews auth changes.", "level": "block" },
    { "path": "infra/**", "reason": "Platform owns Terraform.", "level": "warn" },
    { "path": ".github/workflows/**", "level": "block", "aiOnly": true }
  ],
  "blockOn": ["critical", "high"],
  "forbidNewDependencies": false,
  "requireHumanCommitForAI": true,
  "blockDriftForAI": true,
  "allowedHosts": ["*.acme.com", "api.stripe.com"],
  "blockUnknownHosts": true,
  "approvedVendors": ["stripe", "sentry"],
  "blockUnapprovedVendors": false,
  "ignore": ["**/__snapshots__/**", "docs/generated/**"]
}

ArchCanvas

ArchCanvas maps your cloud accounts into one resource graph. Connected, every review matches the change to it: Terraform resources by address and name, Kubernetes objects, env vars like ORDERS_DB_URL, hostnames the code calls, and the services that deploy this repository. The Infrastructure tab lists the matched resources, their neighbours one and two hops away, and opens the live map with the change painted on it.

1. In ArchCanvas, create an API key with the read scope (it starts with ack_).
2. In visualdiff, Settings → ArchCanvas: paste the key and pick a document, or keep merged for the newest snapshot of every source.
3. Open any report’s Infrastructure tab.

visualdiff only reads from ArchCanvas. A self-hosted ArchCanvas works too: set its address in the same form.

Notifications

Add a Slack incoming webhook or any HTTPS endpoint in Settings. Reviews from webhooks call it on hold (or on every review). Generic webhooks receive a JSON event signed with X-Visualdiff-Signature: sha256=<hmac> using the signing secret shown once when you add it.

API

Send a key as Authorization: Bearer vdk_…. Keys carry the scopes they were minted with: read for reports, write to analyse and store, admin for connections, keys and settings. Requests are limited to 30 per 10 seconds per key. Errors are { error, message } with a trace to quote.

curl -s https://visualdiff.ai/api/v1/analyze \
  -H "Authorization: Bearer $VISUALDIFF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/acme/api/pull/482", "store": true}' \
  | jq '.report.verdict, .url'

git diff origin/main...HEAD | jq -Rs '{diff: .}' \
  | curl -s https://visualdiff.ai/api/v1/analyze -H "Content-Type: application/json" -d @- \
  | jq '.report.plan.totals'

Self-hosting on Railway

visualdiff is one Next.js service and one Postgres database. Create a Railway project from the repository (it builds from the Dockerfile and checks /api/health), add the Postgres plugin, and set these variables. The schema creates itself on first use.

Security

• visualdiff can read pull requests and write one comment and a status. It never pushes, merges or changes settings.
• Host tokens, API keys for ArchCanvas and webhook secrets are encrypted with AES-256-GCM. API keys and sessions are stored only as SHA-256 hashes.
• Addresses you enter (self-managed hosts, ArchCanvas) are fetched over HTTPS only, and private or local network addresses are refused at every redirect.
• Webhooks are verified by HMAC signature or shared secret before anything is read.
• The optional model summary receives counts, paths and finding titles, never code or finding excerpts.
• Logs are one structured line per event; anything that looks like a secret is reduced to its length and last four characters.