CI Directum RX в Gitlab: автоматическая сборка пакетов разработки внутри Docker-контейнеров

Пролог

Пятница, 5 часов вечера. Разраб сидит перед монитором, и усталым немигающим взглядом смотрит на экран. Идёт сборка пакета... Ему пришлось прервать кодинг, чтобы студия, в которой он работал, могла приступить к сборке. Он понимает, что когда вернется к работе, мысль потеряется, вдохновение пропадёт, а качество кода, наверное, станет хуже.

Иногда он читает про CI/CD, даже как-то работал в докере. Ему интересно, можно ли автоматизировать сборку пакета? А что, если после коммита автоматически запускать сборку где-то на сервере? Может, в докере?

Разраб болен, и это первые симптомы. В нём прогрессирует DevOps. Следующие несколько дней он не будет спать и не сможет писать код. Он будет настраивать пайплайны...

Вступление

Эффективная разработка программного обеспечения требует не только качественного кода, но и быстрой и надежной сборки пакетов. Делать это вручную утомительно, затратно по времени и может привести к ошибкам при обновлении разработки. С другой стороны, автоматическая сборка не только решает эти проблемы, но и позволяет разработчику сосредоточиться на написании кода.

Лучшим способом настроить автоматическую сборку является её внедрение в процесс непрерывной интеграции. В этой статье я хочу поделиться своим опытом настройки автоматической сборки в конвейере CI/CD на базе и средствами Gitlab'а с использованием докер-контейнеров и без них.

Предварительные требования

• Gitlab в качестве хранилища репозиториев с решениями Directum RX.
• Сервер на ОС Windows для работы gitlab runner'а
• Docker - если планируете осуществлять сборку внутри контейнера.

Настройка окружения сборки

При настройке автоматической сборки пакетов разработки разумно начать с окружения, в котором эта сборка будет проходить. К вопросу можно подойти двумя путями: с использованием средств контейнеризации и без них. Эволюция CI-конвейера, настройкой которого занимался автор этой статьи, включала оба варианта, поэтому я расскажу как про первый, так и про второй. Рассмотрим их плюсы и минусы, после чего вы сможете решить, какой вас устраивает в большей степени.

Окружение без контейнеров

Наиболее привычным и близким к ручной сборке пакета является вариант без использования контейнеров. Такой подход имеет свои плюсы:

• Простота и понятность: вариант не требует знаний докера.
• Скорость сборки. В контейнере мы клонируем весь репозиторий, в то время как без него достаточно только подтянуть изменения. Плюс не нужно ждать пока докер запустит контейнер. В результате, если сборка в докере занимает 12 минут, то просто на ВМ - около 10.

...и минусы:

• Менее надёжно
• Требует больше вычислительных ресурсов
• Требует больше дискового пространства
• Менее гибко и менее масштабируемо чем с использованием докер-контейнера

Этот способ включает перенос на стенд, где будет проходить сборка, папки с Development studio, а также установку компонент, требуемых для её работы: .NET SDK 6.0, .NET Framework 4.6.1 developer pack, .NET Framework 4.8 developer pack и Git. Все установщики входят в состав дистрибутива и расположены внутри Redist.

Когда все готово, можно провести тестовый запуск среды разработки. Если запуск успешен - то окружение настроено.

Окружение внутри докер-контейнера

В 2023 году про Docker знает каждый, кто имеет отношение к разработке или администрированию. Будучи простым, универсальным и гибким инструментом, он решает целый ряд задач: 

• Обеспечивает изоляцию приложений друг от друга.
• Упрощает развертывание приложений и сервисов, позволяет легко перемещать приложения между средами.
• Сокращает использование вычислительных ресурсов.
• Упрощает управление зависимостями приложений.

А ещё docker можно использовать для автоматической сборки пакетов разработки Directum RX. Ведь зачем делать это на отдельной ВМ, когда это можно сделать внутри контейнера, так ведь? Или нет? Чтобы разобраться, рассмотрим плюсы и минусы такого подхода.

Плюсы:

• Эффективно по ресурсам
• Гибко и переносимо: настроив процесс единожды, его несложно внедрить в CI другого проекта
• Масштабируемо: на одном сервере могут работать несколько контейнеров для нужд разных проектов и к ним можно легко добавить новые.

Минусы:

• Требует знаний докера
• Сборка занимает немного больше времени чем в альтернативном варианте.

Если перечисленные плюсы для вас значат больше, чем минусы, то можно приступать к настройке. Для Создания контейнера в котором будет проходить сборка пакета, нам нужен образ этого контейнера. Наиболее распространенным подходом к созданию образов является написание Dockerfile -- инструкции, содержащей шаги к созданию нужного образа. 

Dockerfile начинается с инструкции FROM. Она указывает на то, какой образ мы используем в качестве базового. Development studio, в которой и будет осуществляться сборка, может работать только на Windows и требует для этого .NET SDK 6.0. Поэтому наш выбор - mcr.microsoft.com/dotnet/sdk:6.0.417-1-windowsservercore-ltsc2022:

FROM mcr.microsoft.com/dotnet/sdk:6.0.417-1-windowsservercore-ltsc2022

Среда разработки требует наличия .NET Framework 4.6.1 developer pack. Скачаем установщик (в нашем примере - из Gitlab package registry) и запустим его с параметрами /q и /norestart. После этого установщик можно удалить:

RUN	C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/NDP461-DevPack-KB3105179-ENU.exe &&\
    NDP461-DevPack-KB3105179-ENU.exe /q /norestart  &&\
	powershell Remove-Item -Path "C:\NDP461-DevPack-KB3105179-ENU.exe" &&\

Среда также требует наличия .NET Framework 4.8 developer pack. Делаем всё то же, что и с 4.6.1.:

RUN C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/ndp48-devpack-enu.exe &&\
    ndp48-devpack-enu.exe /q /norestart  &&\
	powershell Remove-Item -Path "C:\ndp48-devpack-enu.exe" &&\
#   Git

Последнее что требуется студии - это Git. Он также понадобиться чтобы подтягивать из репозитория собираемые решения:

RUN C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/Git-install.exe &&\
    Git-install.exe /VERYSILENT /NORESTART &&\
	powershell Remove-Item -Path "C:\Git-install.exe" &&\

Ключевой компонент нашего образа - это Development studio. Дополнить ей образ можно скачав и распаковав туда архив со средой разработки.

RUN C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/DevelopmentStudio.zip &&\
    powershell Expand-Archive -Path "C:\DevelopmentStudio.zip" -DestinationPath "C:\DevelopmentStudio"  &&\
    powershell Remove-Item -Path "C:\DevelopmentStudio.zip"

Также добавим инструкцию при запуске контейнера чтобы все команды внутри сразу выполнялись в powershell:

CMD ["powershell"]

Если объединить все вместе, получим следующий Dockerfile:

FROM mcr.microsoft.com/dotnet/sdk:6.0.417-1-windowsservercore-ltsc2022

#   .NET Framework 4.6.1 developer pack	
RUN	C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/NDP461-DevPack-KB3105179-ENU.exe &&\
    NDP461-DevPack-KB3105179-ENU.exe /q /norestart  &&\
	powershell Remove-Item -Path "C:\NDP461-DevPack-KB3105179-ENU.exe" &&\
#   .NET Framework 4.8 developer pack
    C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/ndp48-devpack-enu.exe &&\
    ndp48-devpack-enu.exe /q /norestart  &&\
	powershell Remove-Item -Path "C:\ndp48-devpack-enu.exe" &&\
#   Git
	C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/Git-install.exe &&\
    Git-install.exe /VERYSILENT /NORESTART &&\
	powershell Remove-Item -Path "C:\Git-install.exe" &&\
#   Development studio	
	C:\Windows\System32\curl.exe -O --header "Private-Token: <Ваш токен>" https://gitlab.example.ru/api/v4/projects/1/packages/generic/rx-windows/4.7.34.0/DevelopmentStudio.zip &&\
    powershell Expand-Archive -Path "C:\DevelopmentStudio.zip" -DestinationPath "C:\DevelopmentStudio"  &&\
    powershell Remove-Item -Path "C:\DevelopmentStudio.zip"
	
CMD ["powershell"]

Каждая команда RUN создаёт новый слой образа. Для сокращения их числа все команды RUN были объединены в одну.

Dockerfile готов! Теперь образ нужно собрать и опубликовать в реестр контейнеров, откуда его можно будет использовать в пайплайнах CI/CD (например, в Gitlab container registry). Для этого воспользуйтесь командами:

1. docker login - для авторизации в реестре контейнеров
2. docker build - для сборки образа из Dockerfile.
3. docker push - для публикации контейнера в реестр

Настройка gitlab runner

Исполнителем этапов CI/CD в Gitlab является Gitlab runner. Процесс его установки хорошо описан в документации, однако для корректной работы стоит обратить внимание на некоторые моменты.

Без докера:

1. Gitlab runner должен быть установлен на одну машину со средой разработки, в которой будет проходить сборка
2. В config.toml executor = "powershell"

С докером:

1. Виндовый контейнер запустится только на машине с ОС Windows. Значит, gitlab runner вместе с докером должны быть установлены на сервер с Windows.
2. В config.toml executor = "docker"
3. В config.toml в разделе [runners.docker] значение image = имя опубликованного ранее образа
4. В config.toml в разделе [runners.docker] у config.toml значение volumes автоматически написано на манер Linux - ["/cache"]. Необходимо изменить под Windows - ["C:\\cache"]

Создание этапа автоматической сборки в CI-конвейере

Внедрить автоматическую сборку пакета в процесс непрерывной интеграции означает создать и настроить соответствующий этап в конвейере CI/CD. В Gitlab это делается изменением содержимого файла .gitlab-ci.yml, который содержит описание всех этапов. 

Начнём с постановки задачи. Этап должен удовлетворять следующим условиям:

1. По итогу выполнения этапа мы должны иметь свежесобранный пакет актуальной разработки с сопроводительной xml'кой
2. При возникновении ошибки во время выполнения этапа, мы должны быть уведомлены об этом.
3. При возникновении ошибки, нужно иметь возможность проанализировать её причину.
4. Сборка должна происходить автоматически после коммитов в ветки test и master, из которых пакеты публикуются на тестовый и продуктовый контур.

Содержимое .gitlab-ci.yml будет немного отличаться в зависимости от того, настраиваем мы автоматическую сборку в контейнере или нет. Независимо от этого, файл следует сохранить в корень репозитория с прикладной разработкой и закоммитить в Gitlab. Если все сделано правильно, то в разделе CI/CD -> Pipelines на странице проекта в Gitlab'е появится CI/CD-конвейер с нашим этапом. Все настройки этапа можно и нужно менять в соответствии с потребностями на проекте. Если какие-то из них не понятны - настоятельно рекомендую в них разобраться, для этого есть подробная документация.

Сборка пакетов без докера

Если мы планируем собирать пакеты разработки вне контейнеров, то при отсутствии других этапов, итоговый .gitlab-ci.yml может выглядеть следующим образом:

stages:
  - build

build-job:
    variables:
        GIT_STRATEGY: none
        
        BASE_PROJECT_NAME: "base"
        BASE_REPOSITORY_URL: "https://gitlab-ci-token:${CI_JOB_TOKEN}@$CI_SERVER_HOST/$CI_PROJECT_NAMESPACE/$BASE_PROJECT_NAME"
        BASE_REPO_BRANCH: "master"
        PACKAGE_PATH: "$CI_PROJECT_DIR/package.dat"
        XML_TEMPLATE_PATH: "$CI_PROJECT_DIR/$CI_PROJECT_NAME/package.xml"

#       Названия веток при коммитах в которых жоба запускается автоматически
        JOB_AUTO_RUN_BRANCH_PATTERN: "/^master$|^test$/"  
    tags:
        - directum-build
    stage: build
    script:
#       Редачим настройку "GIT_ROOT_DIRECTORY" в _ConfigSettings.xml у Development studio
        - $xmlpath = "C:/DirectumLauncher/etc/_builds/DevelopmentStudio/bin/_ConfigSettings.xml"
        - $xml = [xml](Get-Content $xmlpath)
        - $node = $xml.settings.var | where {$_.name -eq "GIT_ROOT_DIRECTORY"}
        - $node.value = $CI_PROJECT_DIR
        - $xml.Save($xmlpath)
#       Удаляем старые артефакты проекта
        - if(Test-Path "package.dat") {Remove-Item "package.dat" -Force}
        - if(Test-Path "package.xml") {Remove-Item "package.xml" -Force}
#       Подтягиваем изменения для сборки пакета
        - | #work
            if (Test-Path "$CI_PROJECT_NAME")
            {
                git -C $CI_PROJECT_NAME remote set-url origin $CI_REPOSITORY_URL
                git -C $CI_PROJECT_NAME pull --all
                git -C $CI_PROJECT_NAME checkout $CI_COMMIT_BRANCH
            }
            else
            {
                git clone -b $CI_COMMIT_BRANCH $CI_REPOSITORY_URL $CI_PROJECT_NAME
            }
        - | #base
            if (Test-Path "$BASE_PROJECT_NAME")
            {
                git -C $BASE_PROJECT_NAME remote set-url origin $BASE_REPOSITORY_URL
                git -C $BASE_PROJECT_NAME pull --all
                git -C $BASE_PROJECT_NAME checkout $BASE_REPO_BRANCH
            }
            else
            {
                git clone -b $BASE_REPO_BRANCH $BASE_REPOSITORY_URL $BASE_PROJECT_NAME
            }
#       Запускаем сборку пакета
        - C:/DirectumLauncher/etc/_builds/DevelopmentStudio/bin/DevelopmentStudio.exe -c $XML_TEMPLATE_PATH -d $PACKAGE_PATH --increment-version false
    rules:
        - if: $CI_COMMIT_BRANCH !~ $JOB_AUTO_RUN_BRANCH_PATTERN
          when: manual
        - if: $CI_COMMIT_BRANCH =~ $JOB_AUTO_RUN_BRANCH_PATTERN
    artifacts:
        expire_in: 1 mos
        paths:
        - package.dat
        - package.xml

Файл снабжен комментариями, но для лучшего понимания кратко разберемся в происходящем. Начнём с переменных:

• BASE_PROJECT_NAME - Имя проекта Gitlab который включает репозиторий с базовым решением Directum RX.
• BASE_REPOSITORY_URL - URL репозитория с базовым решением.
• BASE_REPO_BRANCH - название ветки с актуальной разработкой репозитория с базовым решением.
• PACKAGE_PATH - путь по которому сохраняется собираемый пакет разработки.
• XML_TEMPLATE_PATH - путь до шаблонного xml-файла указываемого при сборке пакета (в нашем случае он находится внутри репозитория с рабочим решением).
• JOB_AUTO_RUN_BRANCH_PATTERN - regex-паттерн с названиями веток при коммите в которые необходимо собирать пакеты разработки. Нужен для создания условия запуска автоматической сборки.

Все остальные переменные являются предопределенными и объявляются неявно. О том, что каждая значит можно узнать из документации. 

Блок script содержит команды выполняемые Gitlab runner в среде выполнения. Наш скрипт содержит следующие команды:

1. Редактировать _ConfigSettings.xml студии для корректного запуска сборки.
2. Подтянуть изменения из репозиториев с базовой и прикладной разработкой. Для каждого из них...
   1. Обновить URL с новым токеном авторизации для доступа к репозиторию.
   2. Подтянуть изменения всех веток git'а
   3. Переключиться на нужную ветку
3. Запустить сборку пакета разработки.

Блок rules включает условие для автоматического запуска задания на сборку пакета. В данном случае - это соответствие названия ветки regex-паттерну из $JOB_AUTO_RUN_BRANCH_PATTERN. Если ветка не соответствует паттерну, то, при необходимости, задание можно запустить вручную.

Artifacts содержит описание файлов и папок которые являются результатом работы задания. В нашем .gitlab-ci.yml описаны следующие артефакты:

• Пакет разработки package.dat
• Сопроводительный xml package.xml

Сборка пакетов внутри  docker-контейнера

Если у нас подготовлен контейнер, и мы хотим проводить сборку в нём, то итоговый .gitlab-ci.yml будет выглядеть немного иначе.

stages:
  - build

build-job:
    variables:
        GIT_STRATEGY: none
        
        BASE_PROJECT_NAME: "base"
        BASE_REPOSITORY_URL: "https://gitlab-ci-token:${CI_JOB_TOKEN}@$CI_SERVER_HOST/$CI_PROJECT_NAMESPACE/$BASE_PROJECT_NAME"
        BASE_REPO_BRANCH: "master"
        PACKAGE_PATH: "$CI_PROJECT_DIR/package.dat"
        LOGS_PATH: "$CI_PROJECT_DIR/logs"
        XML_TEMPLATE_PATH: "$CI_PROJECT_DIR/$CI_PROJECT_NAME/package.xml"
        
#       Названия веток при коммитах в которых жоба запускается автоматически
        JOB_AUTO_RUN_BRANCH_PATTERN: "/^master$|^test$/" 
    tags:
        - directum-docker-build
    stage: build
    allow_failure: false
    image: registry-gitlab.example.ru/directum/rx/sugero_development_studio
    script:
#       Редачим _ConfigSettings.xml у Development studio
        - $xmlpath = "C:/DevelopmentStudio/bin/_ConfigSettings.xml"
        - $xml = [xml](Get-Content $xmlpath)
        - $node = $xml.settings.var | where {$_.name -eq "GIT_ROOT_DIRECTORY"}
        - $node.value = $CI_PROJECT_DIR
        - $node = $xml.settings.var | where {$_.name -eq "LOGS_PATH"}
        - $node.value = $LOGS_PATH
        - $xml.Save($xmlpath)
#       Подтягиваем изменения для сборки пакета
        - C:\Program` Files\Git\cmd\git clone -b $CI_COMMIT_BRANCH $CI_REPOSITORY_URL $CI_PROJECT_NAME
        - C:\Program` Files\Git\cmd\git clone -b $BASE_REPO_BRANCH $BASE_REPOSITORY_URL $BASE_PROJECT_NAME
#       Запускаем сборку пакета
        - $process = $(Start-Process -FilePath C:\DevelopmentStudio\bin\DevelopmentStudio.exe -ArgumentList "-c $XML_TEMPLATE_PATH -d $PACKAGE_PATH --increment-version false" –PassThru)
        - $process.WaitForExit()
        - | #При неуспешной сборке жоба завершится с ошибкой
            if ($process.ExitCode -ne 0)
            {
                echo "Процесс сборки пакета завершился с ошибкам"
                exit 1
            }
    rules:
        - if: $CI_COMMIT_BRANCH !~ $JOB_AUTO_RUN_BRANCH_PATTERN
          when: manual
        - if: $CI_COMMIT_BRANCH =~ $JOB_AUTO_RUN_BRANCH_PATTERN
    artifacts:
        expire_in: 1 mos
        when: always
        paths:
        - package.dat
        - package.xml
        - $LOGS_PATH

В предыдущей части было дано описание .gitlab-ci.yml, используемому при альтернативном подходе. Поскольку оба решают одну задачу, то файлы очень похожи. Поэтому ниже мы рассмотрим только отличия.

Отличия начинаются с новой переменной "LOGS_PATH". Дело в том, что при появлении ошибок сборки внутри контейнера, их намного сложнее проанализировать, т.к. контейнер вместе с содержимым уничтожается сразу после завершения этапа. Для решения этой проблемы можно сохранять лог-файл среды разработки в качестве еще одного артефакта. Для этого мы дополнительно вносим изменения в параметр "LOGS_PATH" конфигурационного файла студии и немного меняем содержимое блока artifacts, чтобы на выходе иметь ещё один артефакт.

Второе отличие: поскольку с каждым запуском этапа у нас запускается новый контейнер, то вместо git pull мы всегда используем git clone.

Последним отличием является запуск сборки с помощью Start-Process. Дело в том, что в отличии от сборки на ВМ, в контейнере runner не ждёт её завершения и сразу завершает этап, причём без ошибок. Спасением и находкой стал запуск студии через Start-Process. Он позволил не только явно дожидаться окончания процесса, но и проверять его результат с помощью ExitCode.

Заключение

В результате несложных операций мы автоматизировали сборку пакетов разработки, повысили оперативность и надёжность передачи разработки, организовали хранение пакетов средствами Gitlab'а, да и в целом поступили как настоящие DevOps'ы. Разработчик рад, что больше не отвлекается на рутинные задачи, ПМ рад уверенности в том, что машина не забудет про пакет и не ошибётся при сборке. Мир стал чуточку лучше, а жить в нём стало чуточку проще.

Эпилог

Понедельник. 3 часа дня. Разработчик кодит. Прошёл ровно месяц после последнего собранного вручную пакета. Многое изменилось за это время: подход команды к разработке, распределение обязанностей в коллективе, изменился и сам разраб. Внедрив процесс автоматической сборки на проекте и продемонстрировав её эффективность, он стал помогать с этим другим командам. Он собирается продолжать развиваться как DevOps и уже думает о том, какой процесс будет автоматизировать следующим. А мы с вами будем с нетерпением этого ждать и, кто знает, может ещё о нём услышим...

* * *

Автор не DevOps, он только учится. Если у вас возникли предложения, пожелания или вы заметили ошибку, пожалуйста, оставляйте комментарии. Я внимательно с ними ознакомлюсь и отмечу лайкусиком дополню статью.

Также хочу выразить благодарность Алексею Присяжному — самому злостному переносчику DevOps'а в сообществе Directum. Эта статья подготовлена по следам его выступления на DDC в далеком 2022 году. 

Спасибо за внимание и всех благ!