課題解決

Plant UML を使ってデザインすることが多いが、Plant UMLは Mermaid の様に GitHub連携されていないので、IDE 上では図が表示されるものの、GitHub上では.puml が図化されない。これは特にレビュー時に問題で、pumlファイルをコードとしてレビューするか、一旦ブランチを落としてきてローカル上の IDEで確認しなければならない。可能であれば GitHub上に画像表示されていて欲しいところである。

この対応として、Docker コンテナを用いて puml → png と出力する機能と、push 時にそれを自動実行する Actionsを用意した。汎用的に利用できるので利用してみて欲しい。

ディレクトリ構成は以下の様になっていることを想定する。

├── Makefile
├── README.md
├── _docs/
│   └── uml/
│       ├── img/
│       ├── Dockerfile
│       ├── sequence.puml
│       └── class.puml
└── compose.yml

_docs ドキュメント全般を格納
_docs/uml *.pumlドキュメントを格納
_docs/uml/img *puml ドキュメントから生成した png イメージを格納

Dockerfile

Dockerfile の中身は以下のようになっている。内部では GitHubの plantuml からアーティファクトをダウンロードしてそれを元にイメージを生成している。ダウンロードURLは JAR_URL として定義しているが、時間の経過とともに最新のURLを参照して欲しい。

_docs/uml/Dockerfile

# ベースイメージを指定
FROM ubuntu:latest

# パッケージの更新
RUN apt-get update && apt-get install -y \
    default-jre \
    graphviz \
    plantuml \
    curl \
    fonts-noto-cjk

# 作業ディレクトリの指定
WORKDIR /app

ENV JAR_URL='https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-mit-1.2024.7.jar'

RUN curl -L -o 'plantuml.jar' "${JAR_URL}" && \
    chmod +x plantuml.jar

WORKDIR /app/uml

# コンテナ実行
ENTRYPOINT ["java", "-jar", "../plantuml.jar"]
CMD ["-tpng", "-o", "./img", "**/*.puml"]

Makefile

Makefile 上では Dockerfile 操作に関する各種エイリアスを定義している。これらは GitHubActions から利用されるが、手動での実行の際も便利である。

.Phony: build run connect compose-run clean

build:
	@ docker build -t puml _docs/uml

run:
	@ docker run -v ./_docs/uml:/app/uml puml

connect:
	@ docker run -it --entrypoint bash -v ./_docs/uml:/app/uml puml

compose-run:
	@ docker compose run --rm puml

clean:
	@ rm _docs/uml/img/*.png

Workflow定義

GitHub Actions の定義は以下の様に記載する。基本的には main ブランチに push した段階で png イメージが自動生成される。

.github/workflows/plantuml.yml

name: Fix Commit

on: push

jobs:
  fix_commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Fix code
        run: |
          make build
          make run
      - name: Commit changes
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .
          git commit -m "update uml images"
          git push

まとめ

以上の工程で _docs/umlディレクトリ上の *.puml ファイルが全て mainへの push時に画像化される仕組みができあがる。

シンプルな仕組みだが、レビュー時に便利なので試してみて欲しい。