課題解決
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
時に画像化される仕組みができあがる。
シンプルな仕組みだが、レビュー時に便利なので試してみて欲しい。