В этой статье я дам краткую вводную, что такое Archi и ArchiMate. Расскажу о коллективной работе с Archi используя расширение coArchi, после чего предоставлю контейнер позволяющий автоматизировать работу по созданию HTML и PDF документов с ArchiMate моделями. Завершим же, созданием своего GitHub Action, настроим GitHub и GitLab пайплайн с последующей публикацией модели в GitHub/GitLab Pages. В чем основная проблематика и причина появления этой автоматизации? Логично утверждать, что любая автоматика экономит время и выполняет рутину за вас, но основной причиной появления данного инструмента и статьи, является простота публикации моделей (схем). Я столкнулся с тем, что большинству нужно просто посмотреть или продемонстрировать схему, но ни кто не хочет разбираться с установкой дополнительного ПО, подключать к нему плагины, настраивать подключение к git репозиторию. Web-страница с актуальной и интерактивной моделью — это то, что нужно среднестатистическому менеджеру, да и архитектора не побеспокоят просьбой сделать скриншот текущей модели. Для тех кому все подробности не нужны, резюмирую: используя этот GitHub Action или этот контейнер в результате получим такой результат. Набор кроссплатформенных инструментов моделирования Archi предназначен для архитекторов и разработчиков моделей всех уровней. Archi написан на Java и распространяются под лицензией MIT, репозиторий проекта доступен на GitHub. Он обеспечивает низкий порог входа для пользователей работающих с языком моделирования ArchiMate. ArchiMate (в оригинале  Architecture-Animate) — это открытый и независимый язык моделирования  архитектуры предприятия и визуализации архитектуры внутри и за пределами бизнес-процессов. Это технический стандарт от The Open Group, базирующийся на IEEE 1471.  ArchiMate дистанцируется от других языков, таких как UML и BPMN по предназначению для моделирования предприятия. Цель ArchiMate — «быть настолько лаконичным, насколько это возможно» (as small as possible), а не охватить все возможные сценарии.  Основные сущности и типы связей языка ArchiMate можно рассматривать как структуру, так называемую ArchiMate Framework. Слои языка хорошо соотносятся с соответствующими фазами метода разработки архитектуры TOGAF (TOGAF и ArchiMate являются стандартами The Open Group). Модель ArchiMate представляет из себя XML документ и подразумевает наличие инструмента Archi для редактирования и просмотра. Archi позволяет экспортировать модель в виде отчуждаемых файлов, и поддерживает такие форматы: Статический HTML отчет с интерактивной структурой и навигацией; CSV отчет по имеющимся в модели элементам, характеристикам и связям; Jasper отчет в форматах PDF, HTML, RTF, PPT, ODT и DOCX; Экспорт модели в нативном формате XML с расширением .archimate; Экспорт модели в формате Open Exchange XML. coArchi — это расширение Archi, которое позволяет вести коллективную работу над моделями ArchiMate, посредством совместного использования и управления версиями моделей в git репозитории. Для установки расширения перейдите на страницу с списком расширений, найдите в списке coArchi и следуйте инструкциям. Репозиторий проекта на GitHub также содержит дополнительную информацию по настройке и решению проблем в работе, подробности смотрите в wiki. ℹ️ Оригинальный файл модели ArchiMate представляет из себя единый XML документ с расширением .archimate. Для возможности совместного редактирования и слияния изменений, данная модель разбивается плагином coArchi на элементы, где каждый элемент хранится в отдельном файле. Соответственно открыть модель сохраненную в репозитории при помощи coArchi, вы сможете только используя это расширение. Некоторые функции coArchi находятся в стадии разработки и постоянно улучшаются. На текущий момент coArchi версии 0.8.1 имеет ограниченную поддержку специализаций и образов добавленных в Archi 4.9. ℹ️ Обратите внимание, что для работы с репозиторием по SSH средствами плагина coArchi — работают только RSA ключи в формате PEM, о чем написано в разделе вики. Также вам не удастся использовать oauth2 токен (у меня не вышло), к примеру в случае активной двухфакторной аутентификации. Судя по всему проблема связана с JGit используемым в проекте, разработчики плагина пока не дали ответа на это замечание. Как видим, всё же имеются некоторые трудности в настройке окружения, на этапе установки coArchi и клонирования модели зачастую менеджер сдается и просто просит скриншот модели у её авторов. Помимо графического интерфейса, Archi также имеет интерфейс командной строки. Подробную справку о работе с ним вы можете найти в вики проекта. К примеру для вывода справки с доступными аргументами выполните: Получив сведения о том, что у Archi есть CLI, функция экспорта и возможна совместная работа в git репозитории, мы имеем все основания попытаться упаковать всё это в образ контейнера, для дальнейшего использования в пайплайне. Поскольку некоторые библиотеки зависят от наличия драйвера дисплея, для запуска CLI в Linux, нам потребуется установить определенные библиотеки, такие как gtk3 и xvfb. В связи с этим и размер образа становиться заметно больше. Итоговый Dockerfile доступен в репозитории: А для удобства работы со всеми аргументами командной строки и реализации возможности доступа к репозиторию модели с любыми стандартными проколами и методами аутентификации git, был реализован bash сценарий запуска entrypoint.sh: В скрипте реализованы переменные окружения для управления ключевыми параметрами клонирования модели и создания отчета, что упростит применение образа в CI пайплайнах. Клонирование репозитория выполняется привычной утилитой git, а уже после передается Archi как модель. Так мы обходим ограничения самого coArchi. Выполнена обвязка для исполнения задания в GitHub Actions с созданием отдельной ветки используя git subtree и дальнейшей публикацией в GitHub Pages. Выполнена обвязка для более простого запуска заданий в GitLab CI ℹ️ Git subtree выбран не спроста. Как альтернативный вариант в GitHub Pages можно опубликовать файлы из отдельного каталога текущей ветки, к примеру /docs, но в таком случае у нас в основной рабочей ветке появляются лишние автоматические "шумные" коммиты, а вместе с ними и растет размер индекса этой ветки, помимо этого, при ответвлении и слиянии правок у нас появляются конфликты в сгенерированных отчетах, которые просто так не решаются через интерфейс Archi. Образы контейнера доступны в репозиториях: 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 Для демонстрации работы был создан отдельный проект на GitHub и GitLab с примером модели ArchiMetal взятой из официального репозитория archimate и сохраненной при помощи coArchi. При запуске контейнера в среде GitHub Action или GitLab CI в HTML отчет также будут добавлены ссылки на другие отчеты включенные для генерации. Для генерации отчета и публикации его в GitLab Pages необходимо создать файл .gitlab-ci.yml в корне проекта вашей coArchi модели, примерно с таким содержимым: После фиксации изменений в репозитории, у вас должен успешно выполнится пайплайн (пример), а модель опубликоваться в виде web-страницы (пример) в вашем GitLab Pages. Для GitHub был реализован GitHub Action - Deploy Archi Report, который опубликует вашу модель на GitHub Pages из отдельной ветки gh-pages. Чтобы воспользоваться им вам достаточно создать файл в каталоге .github/workflows к примеру .github/workflows/main.yml с таким содержимым: Зафиксировав изменения в репозитории, у вас должен успешно выполнится пайплайн (пример). После первого запуска вам также понадобится указать из какой ветки следует публиковать отчет, по умолчанию это gh-pages. Перейдите в настройки репозитория, в разделе Pages укажите исходную ветку gh-pages и используйте корневой каталог для поиска файлов, примените эти настройки. После этого, публикация будет выполнятся из указанной вами ветки (пример) в вашем GitHub Pages. Благодарю за ваше время и внимание! Успешных вам пайплайнов и актуальных моделей. Присоединяйтесь в телеграмм канал, где я периодически публикую заметки на тему DevOps, SRE и архитектурных решений. DevOps Engineer Expert