Convert PlantUML-Files to SVGs in Gitlab CI/CD

PlantUML is a tool that allows you to create UML-diagrams based on text rather than in a visual editor. This has a few advantages like managing your diagrams in a VCS or copy-pasting blocks from one to another diagram. Read a quick introduction here.

This post will show you how PlantUML-documents can be converted to SVG-files in a Gitlab-pipeline and be stored in the repository. Using SVGs allows you to embedded them on platforms like Confluence or in a README and it also allows you to use PlantUML-features like embedded links, which won’t work in all cases when you render the diagrams on the fly.

The whole Text-To-SVG conversion process will be done in a Gitlab Pipeline, meaning that all the work is done in the .gitlab-ci.yml-file and an extra bash script that will be invoked by the pipeline file.

Starting with .gitlab-ci.yml, we need to install graphviz to allow us to convert all supported diagrams in PlantUML to SVG. The basic ci-file looks like this:

create_svg:
	artifacts:
		paths:
			- '**/*.svg'
			- '**/*.puml'
	before_script:
		- apt-get --yes install graphviz
	script:
		- ./convert_puml.sh

First we tell the pipeline which artefacts it should preserve, in this case all SVG- and PUML-files. Next we install graphviz before the actual script is invoked. After the installation is done, the script convert_puml.sh will be invoked by the pipeline.

The script will first setup some variables that are needed during execution:

#!/bin/sh

set -e
set -x

SCRIPT_DIR=$(dirname $(realpath $0))
PLANTUML_JAR_LINK="https://github.com/plantuml/plantuml/releases/download/v1.2023.11/plantuml-1.2023.11.jar"

It will then install the PlantUML-JAR if it’s not already existing within the build cache:

if [ ! -f $SCRIPT_DIR/plantuml.jar ]; then
	curl -L $PLANTUML_JAR_LINK -o $SCRIPT_DIR/plantuml.jar
fi

Next it will go through all .puml-files, replace potential diagram start- and end-tags (these are used to preview the diagrams directly in VSCode) with the correct @startuml- and @enduml-tags and invoke the downloaded JAR with it, resulting in one SVG-file for each puml-file:

for filename in $(find . -type f -name "*.puml"); do
	result=$(cat $filename | sed "s/\`\`\`plantuml/@startuml/" | sed "s/\`\`\`/@enduml/")
	echo "$result" > $filename.new.puml
	java -jar $SCRIPT_DIR/plantuml.jar "$filename.new.puml" -tsvg
done

Last but not least we need to stage, commit and push all the created SVGs back to the repository. This allows us to link to and embedded them in other pages.

git config --global user.email "${CI_COMMIT_AUTHOR}"
git config --global user.name "${GITLAB_USER_NAME}"
git add *.svg
git commit -m '[Root $CI_COMMIT_SHORT_SHA] Generate SVG-Images'
git remote rm origin && git remote add origin [email protected]:$CI_PROJECT_PATH.git
git push origin HEAD:$CI_COMMIT_REF_NAME

We use some variables that are automatically provided in each pipeline run (User, Current Commit, Current Branch) to push back the images to the repository.

With that, it’s all done and it’s now a working flow from start to finish.