PlantUML with Gitlab Runner

12 Aug 2023 - Jan Bernoth

PlantUML is a robust tool for creating text-based diagrams that can be version-controlled. To leverage it for architectural modeling, integration into an automated pipeline is essential. Here’s how I did it.

PlantUML offers concise and comprehensive documentation. While discussing the architecture of my PhD project, I found the C4 model incredibly beneficial, and, conveniently, PlantUML provides a C4 Plugin. For integration into my LaTeX project, I needed a setup that would allow me to effortlessly create diagrams both locally and within my GitLab repository using runners.

Local setup

Download PlantUML with its latest Release and put the jar into the same directory as the txt diagrams. Go with the terminal into the same directory and compile them all:

Download the latest release of PlantUML and place the .jar file in the same directory as your .txt diagrams. Navigate to that directory using the terminal and compile all the diagrams with the following command:

’’’ java -jar .\plantuml.jar .*.txt ‘’’

That’s it. You can now integrate each generated image into your .tex files.

Let the runner do the rest

To exclude certain files from Git tracking, update your .gitignore with:

pictures/plantuml/*.png
*.jar

For CI/CD integration, the runner requires a distinct job to convert the scripts into images. Ensure that you position the output images in the same location as your local setup. Importantly, avoid pulling these via Git in subsequent jobs.

stages:
  - build_images
  - build_pdf

build_images:
  stage: build_images
  image:
    name: ghcr.io/plantuml/plantuml:latest  # official docker file
    entrypoint: [ "" ]
  script:
    - cd pictures/plantuml
    - java -jar /opt/plantuml.jar ./*.txt
  artifacts:
    paths:
      - .  # we need to save the files for the next job

build_pdf:
  stage: build_pdf
  image: aergus/latex:latest
  script:
  # ...
  variables:
    GIT_STRATEGY: none  # No need to pull again
  artifacts:
    expire_in: 1 day
    paths:
      - main.pdf

In conclusion, all diagrams will be conveniently stored in your image folder. This approach is not limited to LaTeX but can also be employed for generating images for systems like Pandoc.