dsh-skills/skills/drawio-skill/references/pr-bot.md

PR Diagram Bot — reviewing .drawio changes as pictures

Goal: in CI, for every .drawio file a pull request touches, render the base version, the head version, and a colour-coded diff, then post them as a sticky PR comment (and the job summary) so reviewers see pictures instead of raw XML diffs.

Read this when you're setting up (or troubleshooting) automated PR diagram review for a repo.

Pieces

• scripts/prdiff.py — the script. changed_drawios() finds what changed (git diff --name-status); for each file it exports base/head PNGs via the draw.io CLI and, for modified files, chains drawiodiff.py -> autolayout.py -> CLI export into a third diff PNG; render_markdown() turns all of that into one Markdown report.
• .github/actions/drawio-diff/action.yml — a composite action that checks out full history, installs draw.io + Graphviz, runs prdiff.py, uploads the PNGs + report as a build artifact, writes the report to $GITHUB_STEP_SUMMARY, and posts/updates a sticky PR comment.
• .github/workflows/drawio-pr-diff.example.yml — a template workflow that wires the action to pull_request events. It ships as .example.yml and gated with if: false so it does nothing until you copy and adapt it in your own repo (see the comment at the top of that file).

Adopting it in your own repo

1. Copy .github/actions/drawio-diff/ and skills/drawio-skill/ (or at least scripts/prdiff.py, scripts/drawiodiff.py, scripts/autolayout.py) into your repo.
2. Copy .github/workflows/drawio-pr-diff.example.yml to .github/workflows/drawio-pr-diff.yml, drop the if: false guard, and uncomment the pull_request: paths: ["**/*.drawio"] trigger.
3. Give the job permissions: pull-requests: write (already set in the example) — the sticky comment step needs it; contents: read covers the checkout.
4. Push a PR that touches a .drawio file and watch it run.

Runner tooling

The draw.io desktop CLI is Electron-based, so headless CI needs the same setup documented in docs/CI.md "Option A" of this repo: Graphviz (dot, for autolayout.py) and a virtual display (xvfb-run). The composite action installs both by default (latest drawio-desktop .deb + apt-get graphviz xvfb); pass skip-tool-install: true if your runner/container already provides drawio and dot on PATH.

If the draw.io CLI is missing (or fails), prdiff.py does not hard-fail the run — the Markdown report still lists every changed file and its status, just without images, with a note that image export was skipped. git missing (or --repo not being a git repository) IS fatal, since without git there is nothing to diff.

How the sticky comment works

The action tags its comment body with an HTML marker (<!-- drawio-pr-diff-bot -->) and, before posting, searches the PR's existing comments (via gh api .../issues/<n>/comments) for one starting with that marker. If found, it PATCHes that comment in place; otherwise it creates a new one with gh pr comment. This keeps one running comment per PR instead of a new comment on every push.

Running it locally

python3 skills/drawio-skill/scripts/prdiff.py --base origin/main --head HEAD \
  --out-dir drawio-pr -o drawio-pr/report.md

--base/--head are any git refs or SHAs (--head defaults to HEAD); --repo points at a different working tree (default: current directory). Open drawio-pr/report.md to preview exactly what the PR comment will say.