Putting PlantUML diagrams into PR reviews

Diagrams usually get skipped during PR review because most teams keep them in Confluence or PowerPoint. Here’s how to push them through review the same way you push code.

Why we don’t put diagrams in PRs

Common excuses:

• “The diagram is part of the design phase; dev review doesn’t touch it”
• “The diagram is huge, every change touches everything, easy to miss during merge”
• “The review system can’t show the diagram; what would review mean?”

None of these hold up once you have PlantUML + GitHub/GitLab renderers.

Suggested repo layout

1
2
3
4
5
6
7
8
9
10

docs/
  architecture/
    system.puml          # full landscape
    service-a.puml       # service A
    service-b.puml       # service B
  sequences/
    login.puml
    checkout.puml
    refund.puml
  README.md

One .puml file per diagram. kebab-case filenames.

Embedding in PR descriptions

1
2
3
4
5
6
7

## Changes

Fixes session re-creates on login retry timeout.

### Before

![alt](./docs/sequences/login.puml)

Or use a markdown image link:

1

![login flow](https://www.plantuml.com/plantuml/svg/<encoded>)

GitHub renders the encoded URL directly; GitLab does too. The diagram shows up in the PR description.

Make GitHub/GitLab render .puml

GitHub doesn’t render .puml source files directly — .puml is text source; it needs to be rendered to SVG/PNG first. Two approaches:

A. Commit rendered SVGs alongside (recommended)

1
2

# local render
java -jar plantuml.jar -tsvg docs/sequences/login.puml

When you change .puml, also commit the regenerated .svg. The .puml carries the diff; the .svg is the rendered artifact.

Use .gitattributes to mark SVG as diff=image so PR diffs include the diagram visually:

1

docs/**/*.svg diff=image

B. Render script in the repo

1
2
3
4
5
6

#!/bin/bash
# scripts/render-uml.sh
set -e
for f in $(find docs -name '*.puml'); do
  java -jar plantuml.jar -tsvg -failfast2 -nometadata "$f"
done

Run it in CI:

1
2
3
4
5
6
7
8
9

- name: Render PlantUML
  run: bash scripts/render-uml.sh
- name: Commit rendered SVGs
  run: |
    git config user.name github-actions
    git config user.email github-actions@github.com
    git add docs/**/*.svg
    git commit -m "render: regenerate SVGs" || exit 0
    git push

This way PR diffs include SVG, and reviewers can use GitHub’s image diff viewer to see before/after.

Force diagram updates via PR template

.github/PULL_REQUEST_TEMPLATE.md:

1
2
3
4
5
6
7
8
9
10

## Changes

<!-- description of what changed -->

## Diagrams

<!-- If this PR changes interface, state, or flow, add/update .puml and re-render SVG -->
- [ ] I have added/updated the relevant .puml files
- [ ] I have re-rendered the corresponding SVG
- [ ] I have attached the relevant diagram below (plantuml server link or local SVG)

Diagram presence becomes unmissable.

Reviewing the diagrams themselves

Reviewers should write:

“Why is there no arrow between step 4 and step 5 in this sequence diagram? Is it synchronous blocking or async?”

Not:

“Let’s book a meeting to talk about the login flow.”

Reviews happen in a visible, searchable, traceable text stream.

Recommended toolset

Day-to-day workflow

What I use:

1. Edit .puml files
2. VSCode PlantUML extension gives live preview
3. Commit both .puml and rendered .svg
4. CI re-renders SVG and commits back (in case local forgot)
5. PR description links either plantuml.com encoded URL or local SVG
6. Reviewers annotate directly on the SVG

Pitfalls

• plantuml.com rendering in PR preview is slow: PR description URLs to plantuml.com render 1-2s late in GitHub’s markdown preview. Pre-rendered SVGs avoid this.
• CJK fonts break in SVG: plantuml.jar uses the OpenJDK font by default; CJK characters often render as tofu. Pass a config file:

  1 2 3

  java -Djava.awt.headless=true -jar plantuml.jar \ -config scripts/plantuml.cfg \ -tsvg docs/sequences/login.puml

  plantuml.cfg:

  1 2	skinparam defaultFontName "PingFang SC" skinparam defaultFontSize 14

• Don’t split one diagram across multiple .puml files: each file should be the whole story. Splitting fragments the review surface and the reviewer loses context.
• Themes vs dark mode: default theme is loud on GitHub dark. !theme cyborg or !theme black-knight help on dark, but they’re ugly on white. Safest is !theme plain plus custom skinparams that work in both contexts.