We automate work with ArchiMate in CI pipelines

In this article I will give a short introduction to what Archi and ArchiMate are. I will tell you about the collective work with Archi using the coArchi extension, after which I will provide a container that allows you to automate the creation of HTML and PDF documents with ArchiMate models. Let’s finish by creating our own GitHub Action, set up GitHub and GitLab pipeline, and then publish the model to GitHub / GitLab Pages.

What is the main problem and the reason for the emergence of this automation? It is logical to say that any automation saves time and performs the routine for you, but the main reason for the appearance of this tool and article is the ease of publishing models (diagrams). I was faced with the fact that most just need to look at or demonstrate the diagram, but no one wants to deal with installing additional software, connecting plugins to it, setting up a connection to the git repository. A web page with an up-to-date and interactive model is what the average manager needs, and an architect won’t be bothered by asking them to take a screenshot of the current model.

For those who do not need all the details, I will summarize: using this GitHub Action or this container as a result we get such a result.

Example of a web page with a report
Example of a web page with a report

What is Archi and ArchiMate

A set of cross-platform modeling tools Archi intended for architects and modelers of all levels. Archi is written in Java and is licensed under the MIT license. project repository available on GitHub. It provides a low entry threshold for users working with the modeling language. ArchiMate

Archi Modeling Tool Main Window and Workspace
Archi Modeling Tool Main Window and Workspace

ArchiMate (originally Architecture-Animate) is an open and independent language for modeling enterprise architecture and visualizing architecture within and outside of business processes. This technical standard from The open groupbased on IEEE 1471

ArchiMate distances itself from other languages ​​such as UML and BPMN intended for enterprise modeling. ArchiMate’s goal is “to be as small as possible”, not to cover all possible scenarios.

The main entities and types of links of the ArchiMate language can be viewed as a structure, the so-called ArchiMate Framework

The structure of the ArchiMate 3.1 Full Framework language
The structure of the ArchiMate 3.1 Full Framework language

The layers of the language correlate well with the corresponding phases of the architecture design method. TOGAF (TOGAF and ArchiMate are The Open Group standards).

Exporting a model

The ArchiMate model is an XML document and implies an Archi tool for editing and viewing. Archi allows you to export your model as alienable files, and supports the following formats:

  • Static HTML report with interactive structure and navigation;

  • CSV report on the elements, characteristics and relationships available in the model;

  • Jasper report in PDF, HTML, RTF, PPT, ODT and DOCX formats;

  • Export model in native XML format with extension .archimate;

  • Export model in format Open Exchange XML

Collaboration

coArchi is an Archi extension that allows you to collaborate on ArchiMate models by sharing and versioning models in a git repository.

To install the extension, go to the page with list of extensions, find coArchi in the list and follow the instructions. Project repository on GitHub also contains additional information on setting up and troubleshooting work, see details in wiki

ℹ️ The original ArchiMate model file is a single XML document with the extension .archimate… For the possibility of co-editing and merging changes, this model is split by the coArchi plugin into elements, where each element is stored in a separate file. Accordingly, you can only open a model saved in the repository using coArchi using this extension.

Several features of coArchi are under development and are constantly being improved. Currently coArchi version 0.8.1 has limited support for specializations and images added in Archi 4.9.

ℹ️ Please note that to work with the repository via SSH using the coArchi plugin, only RSA keys in PEM format work, as described in wiki section… Also, you will not be able to use the oauth2 token (it did not work for me), for example, in the case of active two-factor authentication. Apparently the problem is related to JGit used in the project, the plugin developers have not yet answered this remark.

As you can see, there are still some difficulties in setting up the environment, at the stage of installing coArchi and cloning the model, the manager often gives up and simply asks for a screenshot of the model from its authors.

Command line interface

Apart from a graphical interface, Archi also has a command line interface. You can find detailed information on working with it in project wiki

For example, to display help with the available arguments, run:

./Archi -application com.archimatetool.commandline.app 
  -consoleLog -nosplash --help

Archi container image

Having received information that Archi has a CLI, an export function, and possible collaboration in the git repository, we have every reason to try to pack all this into a container image for further use in the pipeline.

Since some libraries depend on the presence of a display driver, in order to run the CLI on Linux, we need to install certain libraries such as gtk3 and xvfb. In this regard, the size of the image becomes noticeably larger.

The final Dockerfile is available at repositories:

And for the convenience of working with all command line arguments and implementing the ability to access the model repository with any standard punctures and git authentication methods, a bash startup script was implemented entrypoint.sh:

  • The script implements environment variables to control the key parameters of cloning a model and creating a report, which will simplify the use of the image in CI pipelines.

  • Cloning the repository is done with the usual git utility, and then it is passed to Archi as a model. This is how we get around restrictions coArchi itself.

  • The binding for the execution of the task in GitHub Actions has been completed with the creation of a separate branch using git subtree and further publication in GitHub Pages.

  • Made a binding for easier launching of jobs in GitLab CI

ℹ️ Git subtree was chosen for a reason. Alternatively, in GitHub Pages, you can publish files from a separate directory of the current branch, for example /docs, but in this case, we have unnecessary automatic “noisy” commits in the main working branch, and along with them the size of the index of this branch grows, besides this, when we fork and merge edits, we have conflicts in the generated reports, which are just like that are not resolved through the Archi interface.

Container images are available in the repositories:

  • Ghcr ghcr.io/woozymasta/archimate-ci:4.9.1-1.0

  • Quay quay.io/woozymasta/archimate-ci:4.9.1-1.0

  • DockerHub docker.io/woozymasta/archimate-ci:4.9.1-1.0

Pipeline

To demonstrate the work, a separate project was created on Github and Gitlab with example model ArchiMetal taken from the official repository archimate and saved with coArchi.

When you run the container in the GitHub Action or GitLab CI environment, links to other reports included for generation will also be added to the HTML report.

Additional links to report files
Additional links to report files

GitLab pipeline

To generate a report and publish it to GitLab Pages you need to create a file .gitlab-ci.yml in the project root of your coArchi model, with content like this:

---
pages:
  stage: build
  image:
    name: quay.io/woozymasta/archimate-ci-image:4.9.1-1.0.2
    entrypoint: [""]

  script:
    - /opt/Archi/entrypoint.sh
    
  variables:
    ARCHI_HTML_REPORT_ENABLED: "true"
    ARCHI_JASPER_REPORT_ENABLED: "true"
    ARCHI_JASPER_REPORT_FORMATS: "PDF,DOCX"
    ARCHI_CSV_REPORT_ENABLED: "false"
    ARCHI_EXPORT_MODEL_ENABLED: "true"

  rules:
    - if: $CI_COMMIT_BRANCH != null || $CI_PIPELINE_SOURCE == "merge_request_event"
      exists:
        - model/folder.xml

  artifacts:
    name: "$CI_JOB_NAME from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
    expire_in: 30d
    paths:
      - public

After committing the changes to the repository, you should have successfully completed the pipeline (example), and the model is published as a web page (example) in your GitLab Pages.

GitHub pipeline

A GitHub Action was implemented for GitHub – Deploy Archi Reportwhich will publish your model to GitHub Pages from a separate branch gh-pages… To use it, you just need to create a file in the directory .github/workflows eg .github/workflows/main.yml with content like this:

---
jobs:
  archi_report:
    permissions:
      contents: write
      pages: write
    runs-on: ubuntu-latest
    name: Deploy Archi report HTML to GitHub Pages
    steps:
      - name: Check out the repo
        uses: actions/checkout@v2

      - name: Deploy Archi report
        id: archi
        uses: WoozyMasta/archimate-ci-image@4.9.1-1.0.2
        with:
          archiHtmlReportEnabled: true
          archiJasperReportEnabled: true
          archiJasperReportFormats: PDF,DOCX
          archiCsvReportEnabled: false
          archiExportModelEnabled: true
          githubToken: ${{ secrets.GITHUB_TOKEN }}

After committing the changes to the repository, you should have successfully completed the pipeline (example). After the first launch, you will also need to specify from which branch the report should be published, by default it is gh-pages… Go to the repository settings, in the Pages section, specify the source branch gh-pages and use the root directory to search for files, apply these settings.

Publishing Settings in GitHub Pages
Publishing Settings in GitHub Pages

After that, the publication will be executed from the branch you specified (example) in your GitHub Pages.


That’s all

Thank you for your time and attention! Successful pipelines and current models.

Join in telegram channelwhere I post periodically on DevOps, SRE, and architecture.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *