Diagrams with PlantUML + GitHub Actions

As we discussed here, diagramming is the inevitable activity of software architect and other developers. Also, here and here we discuss elegance of software documentation, that each project must have only one long README file. Also, your repository should have as little as possible of static files, like images, pdf, etc. Simply because, git doesn’t understand how to do versioning on them. In this guide, I will show how to compile your diagrams, written in PlantUML notation to SVGs. As always, fully automated, on GitHub.

Create .puml Diagram

First, let’s create a new diagram in PlantUML notation:

@startuml
actor       TelegramUser as user
participant Bot as bot
participant Hub as hub
database    Database    as db
participant Notifications as notifications
participant GitHub as github

user -> bot : Chat ID
bot -> hub : Token, Chat ID
hub -> notifications: GitHub Token
hub -> db: Chat ID, Token
notifications -> github: GitHub Token
github --> notifications: Subscription, Data Stream
notifications --> hub: Token, Data Stream
hub -> db: Chat ID by Token
db --> hub: Chat ID
hub --> bot: Chat ID, Data Stream
bot --> user: Data Stream
@enduml

Create GitHub Workflow:

Then we need to create simple GitHub action for PlantUML. On each new change it will automatically compile the .puml into SVG and push to the git branch. Here it is:

name: plantuml
on:
  push:
    paths:
      - '**.puml'
    branches:
      - master
permissions:
  contents: write
jobs:
  plantuml:
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout Source
        uses: actions/checkout@v2
      - name: Generate SVG Diagrams
        uses: holowinski/plantuml-github-action@main
        with:
          args: -v -tsvg diagrams/*.puml
      - name: Commit changes
        uses: EndBug/add-and-commit@v9
        with:
          author_name: <github nickname>
          author_email: <git email>
          message: 'diagram generated'
          # destination folder
          add: 'diagrams/*'

Pay attention to that, this workflow should be in the master branch first.

Create Pull Request with Diagram Changes

Merge it

After merging it into master branch, diagram will be compiled to SVG and pushed there.

Get the Diagram

Diagramming made easy!

Full example at blamer-io/hub/#31; Result is here.