PlantUML in GitLab

Utility project to test PlantUML files rendering and the "!include" directive in these files, that are used in the UML diagrams of the EMERALD project.

Problem of "!include" clause in puml files

The typical "!include" directive of PlantUML (that search files in folders) doesn't work in Gitlab (see Wiki Page Plantuml using !include). The renderer is a separate server that is unable to find the included files. A workaround is to place the files in some url publicly available.

The UML files of EMERALD typically include several common files to define common graphical elements (arrows, colors, names, etc.). For example:

@startuml 

RCM Sequence Diagram
!include ..\roles.wsd
!include ..\color_pallette.wsd

[..]

@enduml

PlantUML blocks in self-managed GitLab installations

PlantUML blocks ("plantuml** ... **") inside markdown files didn't render in Tecnalia's Gitlab (self-managed version), unlike in the Gitlab server (see, for example https://gitlab.com/schurzi/playground/-/blob/main/markdown.md), where this is configured by default. You need to install a separate PlantUML server, ans configure Gitlab to connect to it. After completing the integration, PlantUML converts plantuml blocks to an HTML image tag, with the source pointing to the PlantUML instance. The PlantUML diagram delimiters @startuml/@enduml aren’t required anymore, as these are replaced by the plantuml block.

In markdown files (*.md):

```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
```.

UPDATED: Jul/2024: This was solved installing the corresponding UML server and configuring git.code.tecnalia.dev to connect to it and finally render the plantUML text files as diagrams. Examples:

• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/markdown_uml_1.md Uses "!include http..." in a markdown (*.md) file
• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/markdown_uml_2.md Uses "::include{file=roles.puml}" in a markdown (*.md) file

PlantUML files in GitLab

PlantUML files (*.uml, *.puml...) not rendering in GitLab repos was a long-time known issue (https://gitlab.com/gitlab-org/gitlab/-/issues/17325). The workaround for this could be to check out the repos locally and see the figures using Visual Studio Code with a PlantUML plugin or similar tools.

UPDATED: Feb/2025: This has been finally solved and included in the release 19.7 (see merge request 179301).Now the .pu or .puml files are rendered (when PlantUML integration is enabled) on the GitLab instance. It adds a rich view for graph files. Supported extensions are: mermaid
plantuml
pu
puml
iuml
d2
dot
gv
noml
vg
vl

Hopefully, this feature will be automatically translated to Tecnalia's Gitlab when the release is updated (actual version is v17.8.2).

Examples:

• https://gitlab.com/schurzi/playground/-/blob/main/plantuml_include/included_part.iuml renders the diagram
• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml renders only text

UPDATED: Mar/2025: Tecnalia's GitLab was updated to Community Edition v17.9.1 Now, the puml files are rendered as diagrams!!

Examples:

• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml

• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/included_part.iuml

• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/bad_including.puml (includes a wrong !including clause, and gives an error :-())

• https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/including.puml (includes a correct (https://) !including clause!)