How do you actually review
a BPMN change in a pull request?

Every time a BPMN file changed in a pull request, we ran into the same problem: there was no good way to actually review it.

XML diffs are unreadable

BPMN files are XML, and XML diffs are fine when the change is small, for example rename a task, add a simple attribute, update a condition. But once a process model reaches any real size and complexity, even modest changes produce diffs that are genuinely impossible to interpret. A rerouted flow touches the sequence connection, the source shape, the target shape, and a dozen layout coordinates. The actual change might easily get lost in the mess.

What we tried

The obvious "fix" was to check out the branch, open both versions in the BPMN editor, and compare them manually. This worked, but it was four or five steps every time and had to be repeated after every new commit during the review cycle.
We also tried dedicated web-based diff tools — you uploaded the before and after files and they showed you what changed on the canvas. Same problem: find the base version, download it, find the updated version, download that, upload both. And that was just for one file... often we found ourselves modifying multiple BPMN files (subprocesses) in the same pull request.

We also tried attaching screenshots to the PR description so reviewers could at least see the process. It held up for simple structural changes, but fell apart as soon as the model had property changes, condition updates, or anything not visible from the shape layout alone. All of these required additional images.. And the moment a reviewer requested a change, the screenshots were stale.

Every method we tried had the same shape: it required someone to do something manually, outside the pull request, that would need to be done again on the next commit.

Creation of Flowver

We wanted the visual diff to just be there automatically. Open the PR, see what changed on the diagram — no downloads, no uploads, no separate tool, no stale screenshots. And when the developer pushes a fix, the diff should update automatically. We wanted the review to happen in a single, dedicated place.

That's Flowver. A GitHub App that watches for .bpmn changes in pull requests and posts a visual diff as a Check Run — automatically, for every commit, with no manual work. If you've been storing BPMN files in Git and wrestling with the same review problems, it's what we built for ourselves and what we're opening up to other teams.