Содержание:

• Знакомство и установка Jenkins
• Установка необходимого софта
  • Запуск Jenkins
  • Настройка GitLab
  • Настройка платформы для сборки (msbuild)
    • Необходимые для сборки файлы и настройки
    • Для понимания работы процесса msbuild
  • Возможные ошибки и их решения
  • Ссылки на документацию

---

Знакомство и установка Jenkins

CI (Continuous Integration, Непрерывная Интеграция) — это методология разработки и набор практик, при которых в код вносятся небольшие изменения с частыми коммитами. И поскольку большинство современных приложений разрабатываются с использованием различных платформ и инструментов, то появляется необходимость в механизме интеграции и тестировании вносимых изменений.

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

Jenkins — программная система с открытым исходным кодом на Java, предназначенная для обеспечения процесса непрерывной интеграции (CI) программного обеспечения. Он является чрезвычайно расширяемой системой из-за внушительной экосистемы разнообразных плагинов. Настройка пайплайна осуществляется в декларативном или императивном стиле на языке Groovy, а сам файл конфигурации (Jenkinsfile) располагается в системе контроля версий вместе с исходным кодом.\

Jenkins Pipeline — набор плагинов, позволяющий определить жизненный цикл сборки и доставки приложения как код. Он представляет собой Groovy-скрипт с использованием Jenkins Pipeline DSL и хранится стандартно в системе контроля версий.

Существует два способа описания пайплайнов — скриптовый и декларативный.

1. Скриптовый

node {
  stage('Example') {
      try {
          sh 'exit 1'
      }
      catch (exc) {
          throw exc
      }
  }
}

2. Декларативный

pipeline {
  agent any
  stages {
      stage("Stage name") {
          steps {}
      }
  }
}

Литература для ознакомления с синтаксисом и шагами

Они оба имеют структуру, но в скриптовом она вольная — достаточно указать, на каком слейве запускаться (node), и стадию сборки (stage), а также написать Groovy-код для запуска атомарных степов.

Декларативный пайплайн определен более жестко, и, соответственно, его структура читается лучше.

Общая схема непрерывной интеграции с Jenkins:

1. Сначала разработчик фиксирует код в хранилище исходного кода. Тем временем сервер Jenkins регулярно проверяет наличие изменений в хранилище.
2. Вскоре после того, как происходит фиксация, сервер Jenkins обнаруживает изменения, произошедшие в репозитории исходного кода. Дженкинс потянет эти изменения и начнет готовить новую сборку.
3. Если сборка не удалась, соответствующая команда будет уведомлена.
4. Если сборка прошла успешно, Jenkins развертывает встроенный тестовый сервер.
5. После тестирования Jenkins генерирует обратную связь и затем уведомляет разработчиков о результатах сборки и тестирования.
6. Он продолжит проверять хранилище исходного кода на предмет изменений, внесенных в исходный код, и весь процесс будет повторяться.

Без Jenkins	Используя Jenkins
Весь исходный код построен и протестирован. Поиск и исправление ошибок в случае сбоя сборки и тестирования трудоёмко и занимает много времени, что, в свою очередь, замедляет процесс доставки программного обеспечения.	Каждый коммит, сделанный в исходном коде, создается и тестируется. Таким образом, вместо проверки всего исходного кода разработчикам нужно сосредоточиться только на конкретном коммите. Это приводит к частым выпускам нового программного обеспечения.
Разработчики должны ждать результатов испытаний	Разработчики знают результат тестирования каждого коммита, сделанного в исходном коде на ходу
Весь процесс ручной	Вам нужно только зафиксировать изменения в исходном коде, и Jenkins автоматизирует остальную часть процесса для вас.

Страница с руководством по установке и настройке Jenkins

---

Установка необходимого софта

1. Скачиваем Java с официального сайта

2. Скачиваем Jenkins с официального сайта

3. Устанавливаем Java: При установке Java никаких специфических настроек не требуется (рекомендую обратить внимание на место установки)

4. Устанавливаем софт для Jenkins

• При выборе типа входа в систему выбираем "Run service as LocalSystem"
• Выбираем и тестируем порт (предпочтительно 8080)
• Указываем место где стоит Java
• Выбираем дополнительные модули для Jenkins (Можно ничего не выбирать)
• Завершаем установку

После установки откроется браузер по умолчанию, в котором откроется страница Jenkins. В связи с дальнейшими настройками, Jenkins будет переустановлен, потому не имеет смысла продолжать работать в этой странице!

• В файле jenkins.xml по адресу C:\Program Files\Jenkins изменяем несколько строк:

<env name="JENKINS_HOME" value="D:\Jenkins\.jenkins"/>
<arguments> -Dfile.encoding=UTF-8 -Dpermissive-script-security.enabled=true -Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "C:\Program Files\Jenkins\jenkins.war" --httpPort=-1 --httpsPort=8080 --webroot="D:\Jenkins\war" </arguments>
<pidfile> D:\Jenkins\jenkins.pid </pidfile>

После сохранения jenkins.xml изменится локальная директива Jenkins, сменит протокол с http:// на https:// и примет исходную кодировку UTF-8

• Сохраняем файл
• Настраиваем и перезагружаем службу Jenkins
  • Чтобы открыть Службы, нажмите сочетание клавиш "Win" + R, в открывшемся окне "Выполнить" введите services.msc и нажмите клавишу Enter
  • Находим службу "Jenkins", нажимаем на ней правой кнопкой мыши и выбираем "Свойства"
  • Во вкладке "Вход в систему" выбираем "С учетной записью" и нажимаем кнопку "Обзор"
  • В "Размещение" выбираем "Весь каталог", нажимаем "Ок"
    
  • В поле для текста вводим часть имени пользователя и нажимаем на кнопку "Проверить имена", после чего выбираем нужное нам имя и нажимаем "Ок"
    
  • Заполняем поля паролей, нажимаем "Применить", "Ок"
  • Находим службу "Jenkins", нажимаем на ней правой кнопкой мыши и выбираем "Перезагрузить"

5. Переходим в браузере на адрес https://localhost:8080/
   • Требуется ввести пароль, который лежит в файле initialAdminPassword по адресу указанному на странице браузера. D:\Jenkins\.jenkins\secrets
   • Выбираем установку с предварительным выбором плагинов
   • В поиске плагинов ищем Git, и выбираем GitLab, Git Parameter, SSH Agent и устанавливаем это всё
6. Создаем пользователя Jenkins
7. Выбираем адрес для Jenkins (Советую оставить как есть)

Запуск Jenkins

Для того что бы открыть Jenkins можно использовать разные варианты адреса

• Перейдя по ссылке
• https://localhost:8080/
• https://jenkins:8080/ Имя хоста Такой вариант использования, чаще всего, применяется при обращении со стороны в одной локальной сети (В нашем случае от GitLab, но его можно использовать и напрямую)
• https://jenkins.mega-pol.ru:8080/ Или же такой вариант, по аналогии с пердыдущим

Настройки Jenkins и важные особенности ищите в другой главе

---

Настройка GitLab

1. Создание WebHook
   • Открываем страницу репозитория
   • Слева в колонке в выпадающем списке "Settings" ищем "Webhooks"
   • В поле "URL" нужно вставить адрес к настроенному pipeline в Jenkins

   Обратите внимание, что адрес должен быть не локальный (должен быть адрес сервера Jenkins), и вместо части job должно быть project по аналогии с примером:

   https://jenkins:8080/project/JobForRepo/

   • Выбираем триггеры для хука
   • Ставим галочку в поле "Enable SSL verification" и нажимаем "Add webhook"

Советую после создания WebHook протестировать его. Внизу, под настройками нового хука, есть список созданных "Project Hooks", где у каждого хука есть кнопка "Тест". В выпадающем списке например выбираем Push events

2. Визуализация коммит статуса и разрешения MR
   • В нужном нам репозитории, слева в колонке в выпадающем списке "Settings" ищем "General"
     • В разделе "Merge requests" ищем поле "Merge checks", где ставим галочку на Pipelines must succeed
     • Внизу в этом разделе сохраняем изменения "Save changes"
   • Так же в нужном нам репозитории, слева в колонке в выпадающем списке "Settings" ищем CI/CD
     • В разделе "Auto DevOps" отключаем Default to Auto DevOps pipeline
     • Внизу в этом разделе сохраняем изменения "Save changes"

Теперь на главном экране репозитория, а так же в окне "Merge requests" будет отображаться "Commit status" (Зеленая галочка напротив Pipeline и кнопки Merge)
А так же не получится сделать "Merge" без успешной сборки от Jenkins

---

Настройка платформы для сборки (msbuild)

Необходимые для сборки файлы и настройки

Для того что бы не устанавливать на платформу Delphi, но сборка проектов Delphi всё же происходила на Jenkins, делаем следующее

1. Создаем на сервере соответствующий путь C:\Program Files (x86)\Embarcadero\Studio\22.0 версия может быть другой

2. Копируем в эту локацию с рабочей платформы следующие папки:

   • bin
   • bin64
   • lib
     Здесь находится необходимый файл rsvars.bat

Рабочая платформа подразумевает, что необходимо убедиться в том, что проект собирается в Delphi.

3. Создаем на сервере соответствующий путь C:\Users\Jenkins\AppData\Roaming\Embarcadero (В нашем случае пользователь Jenkins)

4. Необходимо копировать в эту локацию с рабочей платформы папку BDS (В которой лежит файл EnvOptions.proj)
   Здесь находятся пути к файлам необходимым для сборки

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

• "C:\Program Files (x86)\Embarcadero\Studio\22.0\bin\rsvars.bat" - Здесь находятся команды для правильной сборки проекта Возможна другая версия Delphi
• msbuild D:\RootRepo\RTL.groupproj - Это пример запуска msbuild. В вашем случае надо указать Ваш адрес проекта для сборки.

Для понимания работы процесса msbuild

MSBuild всегда идет с .NET Framework и лежит он в определенном месте, для того что бы он заработал существует в файлах Delphi файсткрипт, определяющий все переменные окружения нужные для сборки проектов rsvars.bat. В свою очередь, во время сборки msbuild обращается к файлу CodeGear.Common.Targets, в котором есть EnvOptions

1. rsvars.bat
   Файл содержит в себе переменные окружения. Он требуется для определения конкретного msbuild (Их может несколько, в зависимости от Framework)

2. msbuild
   Если установлена Delphi, то MSBuild уже тоже есть, и Delphi его использует. Скорее всего, это каталог %WINDIR%\Microsoft.Net\Framework\v3.5, либо найти в каталоге .Net 4.0/4.5/4.6. Но можно и скачать отдельным приложением с сайта Microsoft.

3. CodeGear.Common.Targets
   И если мы откроем файл в каталоге Delphi С:\Program Files\Embarcadero\Studio\20.0\Bin\CodeGear.Delphi.Targets, то мы увидим там ещё один MSBuild-скрипт, в котором объявлена задача Build: <Target Name="Build"...

4. EnvOptions
   Если вы войдете в систему Hudson или Jenkins как служба Windows, используя учетную запись, которая никогда не использовалась для входа в систему Windows, никогда не запускала BDS.exe, вы получите эту проблему. Утилита MSBUILD от Microsoft должна вызывать DCC32, которая является лицензированным коммерческим программным обеспечением, а для лицензирования компиляции командной строки Delphi и настройки среды требуется, чтобы вы запустили IDE в качестве учетной записи и чтобы ваша учетная запись сборки jenkins и компьютер были лицензированы должным образом.

   Решение этой проблемы описано в подразделе "Необходимые для сборки файлы и настройки"

---

Возможные ошибки и их решения

1. При выполнении msbuild встречаются ошибки сборки. Часто они связанны с ненайденными файлами сборщиком. В данном руководстве, должно быть всё учтено, однако я обращу внимание на некоторые файлы и их параметры, что бы было понимание как происходит сборка и что критически важно для успешной работы сборщика.

Все ошибки этого раздела связанны с тем, что на сервер не ставится Delphi, и соответственно, средства для сборки Delphi проектов. Потому ВАЖНО брать файлы с рабочей платформы.

• Если не скопировать папки, указанные во 2 пункте раздела настройка платформы для сборки (msbuild), выйдет, что сборщик не найдет файла rsvars.bat В котором прописаны переменные окружения, в частности: %FrameworkDir%; %FrameworkSDKDir%;. По сути консоль должна обратить внимание на то, что файла нет ""C:\Program Files (x86)\Embarcadero\Studio\22.0\bin\rsvars.bat"msbuild" не является внутренней или внешней командой, исполняемой программой или пакетным файлом.
• При дальнейшей сборке (Когда файл rsvars.bat будет скопирован на сервер), у сборщика возможны следующие ошибки:
  • C:\Program Files (x86)\Embarcadero\Studio\22.0\Bin\CodeGear.Delphi.Targets(407,5): error E1026: File not found: 'Controls.res'
  • C:\Program Files (x86)\Embarcadero\Studio\22.0\Bin\CodeGear.Delphi.Targets(407,5): error E1026: File not found: 'Dialogs.res' Эти ошибки связанны с тем, что в файлах пользователя нет файлов Controls.res, Dialogs.res.
• Так же возможны Предупреждения связанные с фалом CodeGear.Delphi.Targets, в котором сборщик может обратить внимание на то, что бы явно указали скобки "(", ")" в некоторых строках.

Если есть какие-либо ошибки связанные с ненайденными фалами - рекомендую использовать в cmd команду set, которая отобразит текущие параметры переменной среды.

2. Не работает служба Jenkins

• Если служба Jenkins перестала запускаться, то в этом случае необходимо принудительно запустить его из окна служб:

  • Это можно сделать из Диспейчера Задач → Службы → Jenkins. Нажав правой кнопкой мыши по службе, выбираем Запустить

• Если служба запускается и сразу отлючается

  • Проверьте Диспейчер задач. Если там есть процессы, связанные с Java, их стоит отключить.
  • Периодически сама платформа Java обновляется, не внося изменения в Jenkins.

Проверьте файл Jenkins.xml, сравните актуальную директорию вашей Java с содержимым строки executable. Они должны быть идентичны

---

---

---

Ссылки на документацию

• Jenkins

• GitLab

• Git

• Markdown в GitLab

---

В начало | Открыть страницу заново | Страница Home

---