Generate PlantUML in you CI/CD Pipeline

Jon Morley-Jones included in Diagram as Code

2020-07-20 778 words 4 minutes

Contents

This is part of a series creating around PlantUML and Diagrams as Code.

Authoring Plant UML files in Visual Studio Code
Creating Image file from PlantUML using command line
Creating Pipeline to build and check-in Diagrams as Code (This Post)
Optimise the Pipeline

In the previous posts in the series we have looked how to author as well as how to build the PlantUML files using command line tools.

In this post will we build the PlantUML diagrams on check-in.

Getting started

Step 1 - Setup Azure DevOps Project to enable build agent

We are going to configure Azure DevOps Pipeline to build the PNG when we check in the wiki. So the PNG needs to be added to the Repository. Configure the security for the given project follow the steps in this tip https://azuredevops.tips/2020/02/29/repo-allow-build-agent-to-commit-code/ .

Step 2 - Configure Pipeline

Create new Pipeline
Select the location where your PlantUML documents are located.
Create Starter Pipeline

Pipeline to generate PlantUML diagrams

Build PNG files from PUML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
pool:
  vmImage: 'vs2017-win2016'
trigger:
 batch: true
workspace:
    clean: all
    
steps:
- checkout: self
  persistCredentials: true
- task: UseNode@1
  displayName: Install Node
  inputs:
    version: '6.x'
- task: Npm@1
  displayName: Install Node Plant UML
  inputs:
    command: 'custom'
    customCommand: 'install node-plantuml -g' 
- task: PowerShell@2
  displayName: Check Out
  inputs:
    targetType: 'inline'
    script: |
            git config --global user.email "[email protected]"
            git config --global user.name "Your Name"
            git status
            
            git checkout "$Env:BUILD_SOURCEBRANCHNAME"

- task: PowerShell@2
  displayName: Build Images
  inputs:
    targetType: 'inline'
    script: |
            $sourceRoot = "$Env:Build.SourcesDirectory"
            Get-ChildItem $sourceDir -Recurse -Filter "*.puml" |
                Foreach-Object   {
                    $fileWithPath = $_.Fullname         
                    $png =  Join-Path  -Path $_.DirectoryName -ChildPath ("{0}.png" -f $_.Basename ) 
                    $execute = "puml generate $fileWithPath -o $png "; 
                    Invoke-Expression -Command $execute 
                }

- task: PowerShell@2
  displayName: Check In
  inputs:
    targetType: 'inline'
    script: |
            git add --all
            git commit -m "$Env:BUILD_BUILDNUMBER [skip ci]"
            #git checkout "$Env:BUILD_SOURCEBRANCHNAME"
            #git merge "$Env:BUILD_SOURCEBRANCHNAME" -m "$Env:BUILD_BUILDNUMBER"
            #git branch -d "$Env:BUILD_BUILDNUMBER"
            git push origin  
          

Double check Security

The build agent security needs to be configured properly look at https://azuredevops.tips/allow-build-agent-to-commit-code/ this will give the instructions on how to enable the right security settings.

If these settings are set you the pipeline won’t be able to check in the images.

Break it Down

Define Windows Build Agent

1
2
3
4
5
6
7
8
9
# Pipeline to generate PlantUML diagrams
# Build PNG files from PUML

pool:
  vmImage: 'vs2017-win2016'
trigger:
 batch: true
workspace:
    clean: all

Specify a Windows build agent, at the moment this script only works on Windows, I have yet to get it working on other platforms. The build agent will clear out all the content on the build agent, it will also make sure that if multiple changes happen in a short period it will batch up these changes.

1
2
- checkout: self
  persistCredentials: true

Persist Credentials, enables the pipeline to use OAuth token to check in the new PNGs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- task: UseNode@1
  displayName: Install Node
  inputs:
    version: '6.x'
- task: Npm@1
  displayName: Install Node Plant UML
  inputs:
    command: 'custom'
    customCommand: 'install node-plantuml -g' 
    

Install Node and the node-plantuml command line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- task: PowerShell@2
  displayName: Check Out
  inputs:
    targetType: 'inline'
    script: |
            git config --global user.email "[email protected]"
            git config --global user.name "Your Name"
            git status
            
            git checkout "$Env:BUILD_SOURCEBRANCHNAME"

Powershell script configure the git then Check Out the selected branch.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- task: PowerShell@2
  displayName: Build Images
  inputs:
    targetType: 'inline'
    script: |
            $sourceRoot = "$Env:Build.SourcesDirectory"
            Get-ChildItem $sourceDir -Recurse -Filter "*.puml" |
                Foreach-Object   {
                    $fileWithPath = $_.Fullname         
                    $png =  Join-Path  -Path $_.DirectoryName -ChildPath ("{0}.png" -f $_.Basename ) 
                    $execute = "puml generate $fileWithPath -o $png "; 
                    Invoke-Expression -Command $execute 
                }

Powershell script to loop over all the folders to find all files with puml extension. For all the files run puml cli to generate the png files.

1
2
3
4
5
6
7
8
- task: PowerShell@2
  displayName: Check In
  inputs:
    targetType: 'inline'
    script: |
            git add --all
            git commit -m "$Env:BUILD_BUILDNUMBER [skip ci]"
            git push origin              

Add all the new files generated. Commit the changes, note the [skip ci] on the commit, this means that the pipeline won’t be triggered again for the checked in PNGs. The script then pushes in the changes to the server.