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

Как только кто-либо из нашей команды вносит изменения в код (читай мерджит feature-ветку в develop), наш билд-сервер:

• Собирает исходный код и установщик приложения
  
  • проставляет номер сборки, каждый раз увеличивая последнюю цифру. Например, текущая версия нашего ПО 3.3.0.202 часть 3.3.0 когда-то ввёл разработчик (привет, SemVer), а 202 проставляется в процессе сборки.
  • В процессе анализирует качество кода (с использованием SonarQube) и отправляет отчёт во внутренний SonarQube,
• Сразу после сборки запускает автотесты (xUnit) и анализирует покрытие тестами (OpenCover),

Также, в зависимости от ветки, в которую были внесены изменения, могут быть выполнены:

• отправка сборки (вместе с changelog-ом) в один или несколько телеграм-каналов (иногда удобнее брать сборки оттуда).
• публикация файлов в систему автообновления ПО.

Под катом о том, как мы научили Gitlab CI делать за нас бОльшую часть этой муторной работы.

Оглавление

1. Устанавливаем и регистрируем Gitlab Runner.
2. Что нужно знать про .gitlab-ci.yml и переменные сборки.
3. Активируем режим Developer PowerShell for VS.
4. Используем CI для проставления версии во все сборки решения.
5. Добавляем отправку данных в SonarQube.
6. Причёсываем автотесты xUnit + добавляем вычисление покрытия тестами через OpenCover.
7. Послесловие.

Перед началом

Чтобы быть уверенными, что написанное ниже работает, мы взяли на github небольшой проект, написанный на WPF и имеющий unit-тесты, и воспроизвели на нём описанные в статье шаги. Самые нетерпеливые могут сразу зайти в созданный на сайте gitlab.com репозиторий и посмотреть, как это выглядит.

Устанавливаем и регистрируем Gitlab Runner

Для того чтобы Gitlab CI мог что-либо собрать, сначала установите и настройте Gitlab Runner на машине, на которой будет осуществляться сборка. В случае проекта на .Net Framework это будет машина с ОС Windows.

Чтобы настроить Gitlab Runner, выполните следующие шаги:

1. Установите Git для Windows с сайта git.
2. Установите Visual Studio с сайта Microsoft. Мы поставили себе Build Tools для Visual Studio 2019. Чтобы скачать именно его, разверните список Инструменты для Visual Studio2019.
3. Создайте папку C:\GitLab-Runner и сохраните в неё программу gitlab runner. Скачать её можно со страницы [документации Gitlab] (https://docs.gitlab.com/runner/install/windows.html) ссылки скрыты прямо в тексте: Download the binary for x86 or amd64.
4. Запустите cmd или powershell в режиме администратора, перейдите в папку C:\GitLab-Runner и запустите скачанный файл с параметром install (Gitlab runner установится как системная служба).

.\gitlab-runner.exe install

1. Посмотрите токен для регистрации Runner-а. В зависимости от того, где будет доступен ваш Runner:

   
   
   • только в одном проекте смотрите токен в меню проекта Settings > CI/CD в разделе Runners,
   • в группе проектов смотрите токен в меню группы Settings > CI/CD в разделе Runners,
   • для всех проектов Gitlab-а смотрите токен в секции администрирования, меню Overview > Runners.
   
   

2. Выполните регистрацию Runner-а, с помощью команды

   
   

.\gitlab-runner.exe register

Далее надо ввести ответы на вопросы мастера регистрации Runner-а:

• coordinator URL http или https адрес вашего сервера gitlab;
• gitlab-ci token введите токен, полученный на предыдущем шаге;
• gitlab-ci description описание Runner-а, которое будет показываться в интерфейсе Gitlab-а;
• gitlab-ci tags через запятую введите тэги для Runner-а. Если вы не знакомы с этим механизмом, оставьте поле пустым отредактировать его можно позднее через интерфейс самого gitlab-а. Тэги можно использовать для того, чтобы определённые задачи выполнялись на определённых Runner-ах (например, чтобы настроить сборку ПО на Runner-е, развёрнутом на копьютере ОС Windows, а подготовку документации на Runner-е с ОС Linux);
• enter the executor ответьте shell. На этом шаге указывается оболочка, в которой будут выполняться команды; при указании значения shell под windows выбирается оболочка powershell, а последующие скрипты написаны именно для неё.

Что нужно знать про .gitlab-ci.yml и переменные сборки

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

Вбив в поиске содержимое .gitlab-ci.yml для сборки приложения .NET Framework можно найти несколько шаблонов: 1, 2. Выглядят они примерно так:

variables:  # Максимальное количество параллельно собираемых проектов при сборке решения; зависит от количества ядер ПК, выбранного для сборки  MSBUILD_CONCURRENCY: 4  # Тут куча путей до утилит, которые просто оябзаны лежать там, где ожидается  NUGET_PATH: 'C:\Tools\Nuget\nuget.exe'  MSBUILD_PATH: 'C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\15.0\Bin\msbuild.exe'  XUNIT_PATH: 'C:\Tools\xunit.runner.console.2.3.1\xunit.console.exe'  TESTS_OUTPUT_FOLDER_PATH: '.\tests\CiCdExample.Tests\bin\Release\'# Тут указываются стадии сборки. Указывайте любые названия которые вам нравятся, но по умолчанию используют три стадии: build, test и deploy.# Стадии выполняются именно в такой последовательности.stages:  - build  - test# Далее описываются задачи (job-ы)build_job:  stage: build # указание, что задача принадлежит этапу build  # tags: windows # если тут указать тэг, задача будет выполняться только на Runner-е с указанным тэгом   only: # для каких сущностей требуется выполнять задачу    - branches  script: # код шага    - '& "$env:NUGET_PATH" restore'    - '& "$env:MSBUILD_PATH" /p:Configuration=Release /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly' # сборка; ключ clp:ErrorsOnlyоставляет только вывод ошибок; ключ nr:false завершает инстансы msbuild   artifacts: # где по завершении задачи будут результаты, которые надо сохранить в gitlab (т.н. артефакты) и которые можно будет передать другим задачам по цепочке    expire_in: 2 days # сколько хранить артефакты    paths: # список путей, по которым находятся файлы для сохранения      - '$env:TESTS_OUTPUT_FOLDER_PATH'test_job:  stage: test  only:    - branches  script:    - '& "$env:XUNIT_PATH" "$env:TESTS_OUTPUT_FOLDER_PATH\CiCdExample.Tests.dll"'  dependencies: # указание, что для запуска этой задачи требуется успешно завершенная задача build_job    - build_job

И последнее: если нам требуется передавать в скрипт значение параметра, который мы не хотим хранить в самом скрипте (например, пароль для подключения куда-либо), мы можем использовать для этого объявление параметров в gitlab. Для этого зайдите в проекте (или в группе проекта) в Settings > CI/CD и найдите раздел Variables. Прописав в нём параметр с именем (key) SAMPLE_PARAMETER, вы сможете получить его значение в в скрипте .gitlab-ci.yml через обращение $env:SAMPLE_PARAMETER.
Также в этом разделе можно настроить передачу введенных параметров только при сборке защищённых веток (галочка Protected) и/или скрытие значения параметра из логов (галочка Masked).
Подробнее о параметрах окружения сборки смотрите в документации к Gitlab CI.

Активируем режим Developer PowerShell for VS

Скрипт, приведённый выше, уже можно использовать для сборки и вызова тестов. Правда, присутствует НО: крайне неудобно прописывать абсолютные пути к разным установкам Visual Studio. К примеру, если на одной билд-машине стоит Visual Studio 2017 BuildTools, а на другой Visual Studio Professional 2019, то такой скрипт будет работать только для одной из двух машин.

К счастью, с версии Visual Studio 2017 появился способ поиска всех инсталляций Visual Studio на компьютере. Для этого существует утилита vswhere, путь к которой не привязан ни к версии Visual Studio, ни к её редакции. А в Visual Studio 2019 (в версии 16.1 или более новой) есть библиотека, которая умеет трансформировать консоль Powershell в режим Developer Powershell, в котором уже прописаны пути к утилитам из поставки VS.

Как применить

Дописываем переменную к секции Variables:

variables:  VSWHERE_PATH: '%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe'

Затем создаём новую секцию before_msbuild якорем enter_vsdevshell и следующим текстом:

.before_msbuild: &enter_vsdevshell  before_script:    - '$vsWherePath = [System.Environment]::ExpandEnvironmentVariables($env:VSWHERE_PATH)'    - '& $vsWherePath -latest -format value -property installationPath -products Microsoft.VisualStudio.Product.BuildTools | Tee-Object -Variable visualStudioPath'    - 'Join-Path "$visualStudioPath" "\Common7\Tools\Microsoft.VisualStudio.DevShell.dll" | Import-Module'    - 'Enter-VsDevShell -VsInstallPath:"$visualStudioPath" -SkipAutomaticLocation'

И всюду, где нам надо использовать утилиты Visual Studio, добавляем этот якорь. После этого задача сборки начинает выглядеть намного более опрятно:

build_job:  <<: *enter_vsdevshell  stage: build  only:    - branches  script:    - 'msbuild /t:restore /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'    - 'msbuild /p:Configuration=Release /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'  artifacts:    expire_in: 2 days    paths:      - '$env:TESTS_OUTPUT_FOLDER_PATH'

Результат: мы получили полноценную консоль Developer Powershell с прописанными путями к msbuild и многим другим утилитам, которые можноиспользовать при сборке.

Используем CI для проставления версии во все сборки решения

Раньше мы использовали t4 шаблоны для проставления версий: номер версии собиралась из содержимого файла в формате <major>.<minor>.<revision>, далее к ней добавлялся номер сборки из Gitlab CI и он передавался в tt-шаблон, добавляющий в решение везде, где требуется, номер версии. Однако некоторое время назад был найден более оптимальный способ использование команд git tag и git describe.

Команда git tag устанавливает коммиту метку (тэг). Отметить таким образом можно любой коммит в любой момент времени. В отличие от веток, метка не меняется. То есть если после помеченного коммита вы добавите ещё один, метка останется на помеченном коммите. Если попробуете переписать отмеченный коммит командами git rebase или git commit --amend, метка также продолжит указывать на исходный коммит, а не на изменённый. Подробнее о метках смотрите в git book.

Команда git describe, к сожалению, в русскоязычном gitbook не описана. Но работает она примерно так: ищет ближайшего помеченного родителя текущего коммита. Если такого коммита нет команда возвращает ошибку fatal: No tags can describe '<тут хэш коммита>'. А вот если помеченный коммит нашёлся тогда команда возвращает строку, в которой участвует найденная метка, а также количество коммитов между помеченным и текущим.

На заметку: чтобы данная команда работала корректно во всех случаях, автор gitflow даже чуть-чуть поменял скрипты finish hotfix и finish release. Если кому интересно посмотреть обсуждение с автором gitflow, а также увидеть что изменилось (картинка с актуальной схемой в последнем сообщении в треде).

Кстати, по этой же причине если вы используете gitflow, требуется после вливания feature-ветки в develop требуется удалить влитую локальную ветку, после чего пересоздать её от свежего develop:

(обратите внимание на историю git в левой части картинки: из-за отсутствия пути из текущего коммита до коммита с меткой 1.0.5, команда git describe выдаст неверный ответ)

Но вернёмся к автопроставлению версии. В нашем репозитории царит gitflow (точнее его rebase-версия), метки расставляются в ветке master и мы не занываем пересоздавать feature-ветки от develop, а также merge-ить master в develop после каждого релиза или хотфикса.

Тогда получить версию для любого коммита и сразу передать её в msbuild можно добавив всего пару строк к задаче сборки:

build_job:  <<: *enter_vsdevshell  stage: build  only:    - branches  script:    - 'msbuild /t:restore /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'    - '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+)\.(?<minor>[0-9]*)\.(?<patch>[0-9]*)\-(?<commit>[0-9]+)\-g[0-9a-f]+" | Select-Object -First 1'    - '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'    - '[string]$version = "$major.$minor.$patch.$commit"'    - 'msbuild /p:Configuration=Release /p:AssemblyVersionNumber=$version /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'  artifacts:    expire_in: 2 days    paths:      - '$env:TESTS_OUTPUT_FOLDER_PATH'

Как это работает:

1. Мы проставляем метки в формате <major>.<minor>.<revision>.
2. Тогда git describe --long возвращает нам строку, описывающую версию в формате <major>.<minor>.<revision>-<количество новых коммитов>-g<хэш текущего коммита>.
3. Парсим полученную строку через регулярные выражения, выделяя нужные нам части и записывем части в $versionGroup.
4. Преобразовываем четыре найденные подстроки в 4 числа и пишем их в переменные $major, $minor, $patch, $commit, после чего собираем из них строку уже в нужном нам формате.
5. Передаём указанную строку в msbuild чтобы он сам проставил версию файлов при сборке.

Обратите внимание: если вы, согласно gitflow, будете отмечать (тэгировать) ветку master после вливания в неё release или hofix, будьте внимательны: до простановки метки автосборка будет вестись относительно последней существующей ветки. Например, сейчас опубликована версия 3.4, а вы создаёте release-ветку для выпуска версии 3.5. Так вот: всё время существования этой ветки, а также после её вливания в master, но до простановки тэга, автосборка будет проставлять версию 3.4.

Добавляем отправку данных в SonarQube

SonarQube это мощный инструмент контроля качества кода.

SonarQube имеет бесплатную Community-версию, которая способна проводить полный анализ. Правда, только одной ветки. Чтобы настроить её на контроль качества ветки разработки (develop), требуется выполнить следующие шаги (разумеется, помимо установки и развёртывания сервера SonarQube):

1. Создайте в SonarQube новый проект, после чего запомнить его ключ.

   
   

2. Скачайте SonarScanner for MSBuild (с сайта sonarqube.org)[https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-msbuild/] мы используем версию .NET Framework 4.6+.

   
   

3. Распакуйте содержимое архива в папку. Например, в C:\Tools\SonarScanner.

   
   

На заметку: эту утилиту также можно скачать на сборочную машину через NuGet, но тогда надо будет чуть по-иному указывать её путь.

1. Зайдите в параметры CI/CD в свойствах проекта в Gitlab следующие параметры:
   
   • SONARQUBE_PROJECT_KEY ключ проекта,
   • SONARQUBE_AUTH_TOKEN токен авторизации.

Прописывать параметр ключа проекта необходимо для каждого проекта отдельно (ведь у каждого проекта свой уникальный ключ). А параметр токена авторизации желательно скрыть (отметить как Masked) чтобы он не был доступен всем, кто имете доступ к репозиторию или логам сборки.

1. Допишите переменные к секции Variables:

   
   

   variables:SONARSCANNER_MSBUILD_PATH: 'C:\Tools\SonarScanner\SonarScanner.MSBuild.exe'SONARQUBE_HOST_URL: 'url вашего сервера SonarQube'
   

   
   

2. Допишите в задачу тестирования ветки разработки (test_job) команды для запуска анализа кода и уберите зависимость от задачи build_job:

   
   

   test_job:stage: testonly:- /^develop$/<<: *enter_vsdevshellscript:- '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+)\.(?<minor>[0-9]*)\.(?<patch>[0-9]*)\-(?<commit>[0-9]+)\-g[0-9a-f]+" | Select-Object -First 1'- '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'- '[string]$version = "$major.$minor.$patch.$commit"'- '& "$env:SONARSCANNER_MSBUILD_PATH" begin /key:$env:SONARQUBE_PROJECT_KEY /d:sonar.host.url=$env:SONARQUBE_HOST_URL /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN /d:sonar.gitlab.project_id=$CI_PROJECT_PATH /d:sonar.gitlab.ref_name=develop /v:$version /d:sonar.dotnet.excludeGeneratedCode=true'- 'msbuild /t:rebuild /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'- '& "$env:SONARSCANNER_MSBUILD_PATH" end /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN'- '& "$env:XUNIT_PATH" "$env:TESTS_OUTPUT_FOLDER_PATH\CiCdExample.Tests.dll"'
   

   
   

Теперь при каждой сборке ветки develop в SonarQube будет отправляться подробный анализ нашего кода.

На заметку: вообще команда msbuild /t:rebuild полностью пересобирает решение. Вероятно, в большинстве проектов анализ можно было бы встроить прямо в стадию сборки. Но сейчас у нас анализ в отдельной задаче.

Пара слов об использованных параметрах:

• key ключ проекта на сервере SonarQube,
• v собираемая версия. ИМХО отлично комбинируется с предыдущим шагом автопроставления версии,
• sonar.gitlab.project_id ID проекта на сервере Gitlab,
• sonar.gitlab.ref_name название ветки, которое получает сервер SonarQube при передаче результатов анализа,
• sonar.dotnet.excludeGeneratedCode не включать в анализ объекты, отмеченные атрибутом System.CodeDom.Compiler.GeneratedCode (чтобы не оценивать качество автосгенерированного кода).

Причёсываем автотесты xUnit + добавляем вычисление покрытия тестами через OpenCover

Со сборкой более-менее разобрались теперь приступаем к тестам. Доработаем код прогона тестов, чтобы он:

• сам находил библиотеки с тестами,
• прогонял их пачкой через xUnit,
• вычислял тестовое покрытие через OpenConver,
• отправлял результаты покрытия тестами в SonarQube.

На заметку: обычно в паре с OpenCover используют ReportGenerator, но при наличии SonarQube мы с тем же успехом можем смотреть результаты через его интерфейс.

Для настройки выполним следующие шаги:

1. Скачайте OpenCover в виде zip-файла с сайта github.

   
   

2. Распакуйте содержимое архива в папку. Например, в C:\Tools\OpenCover.

   
   

На заметку: эту утилиту также можно скачать на сборочную машину через NuGet, но тогда надо будет чуть по-иному указывать её путь.

1. Допишите переменные к секции Variables:

   
   

   variables:OBJECTS_TO_TEST_REGEX: '^Rt[^\n]*\.(dll|exe)$'OPENCOVER_PATH: 'C:\Tools\opencover-4.7.922\xunit.console.exe'OPENCOVER_FILTER: '+[Rt.*]* -[*UnitTests]* -[*AssemblyInfo]*'OPENCOVER_REPORT_FILE_PATH: '.\cover.xml'
   

   
   

2. Модифицируйте задачу тестирования ветки разработки (test_job), чтобы она включала и команды вызова OpenCover:

   
   

test_job:  stage: test  only:    - /^develop$/  <<: *enter_vsdevshell  script:    - '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+)\.(?<minor>[0-9]*)\.(?<patch>[0-9]*)\-(?<commit>[0-9]+)\-g[0-9a-f]+" | Select-Object -First 1'    - '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'    - '[string]$version = "$major.$minor.$patch.$commit"'    - '& "$env:SONARSCANNER_MSBUILD_PATH" begin /key:$env:SONARQUBE_PROJECT_KEY /d:sonar.host.url=$env:SONARQUBE_HOST_URL /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN /d:sonar.gitlab.project_id=$CI_PROJECT_PATH /d:sonar.gitlab.ref_name=develop /v:$version /d:sonar.cs.opencover.reportsPaths="$env:OPENCOVER_REPORT_FILE_PATH" /d:sonar.dotnet.excludeGeneratedCode=true'    - 'msbuild /t:rebuild /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'    - '$dllsToRunUnitTesting = @(Get-ChildItem "$env:TESTS_OUTPUT_FOLDER_PATH" -Recurse) | Where-Object {$_.Name -match $env:OBJECTS_TO_TEST_REGEX} | ForEach-Object { """""$_""""" } | Join-String -Separator " "'    - '& "$env:OPENCOVER_PATH" -register -target:"$env:XUNIT_PATH" -targetargs:"$dllsToRunUnitTesting -noshadow" -filter:"$env:OPENCOVER_FILTER" -output:"$env:OPENCOVER_REPORT_FILE_PATH" | Write-Host'    - 'if ($?) {'    - '[xml]$coverXml = Get-Content "$env:OPENCOVER_REPORT_FILE_PATH"'    - '$sequenceCoverage = $coverXml.CoverageSession.Summary.sequenceCoverage'    - '$branchCoverage = $coverXml.CoverageSession.Summary.branchCoverage'    - 'Write-Host "Total Sequence Coverage <!<$sequenceCoverage>!>"'    - 'Write-Host "Total Branch Coverage [![$branchCoverage]!]"'    - '} else {'    - 'Write-Host "One or more tests failed!"'    - 'Throw'    - '}'    - '& "$env:SONARSCANNER_MSBUILD_PATH" end /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN'

Обратите внимание: в begin-команде запуска sonar scanner-а появился дополнительный параметр /d:sonar.cs.opencover.reportsPaths.

1. (необязательный пункт) Ненадолго возврващаемся в Gitlab, заходим в меню проекта Settings > CI/CD и находим на странице настроек параметр Test coverage parsing. Указываем в нём регулярное выражение, которое позволит Gitlab-у также получать информацию о покрытии тестами приложения:
   
   • если хочется видеть значение покрытия тестов по строкам кода (его ешё называют Sequence Coverage или Statement Coverage), указываем выражение <!<([^>]+)>!>,
   • если хочется видеть значение покрытия тестов по веткам условных операторов (его называют Decision Coverage или Branch Coverage), указываем выражение \[!\[([^>]+)\]!\].

А теперь комментарии по изменениям в скрипте.

Длинная строка, начинающаяся с объявления переменной $dllsToRunUnitTesting, нужна для того, чтобы найти все библиотеки нашего приложения, которые потом будут участвовать в расчёте тестового покрытия. При этом выбираются они по регулярному выражению, заданному в параметре $env:OBJECTS_TO_TEST_REGEX (мы же не хотим, например, учитывать в покрытии библиотеки .net или сторонних nuget-пакетов). Пути ко всем найденным библиотекам склеиваются в строку с разделителем пробелом и двумя двойными кавычками для каждого параметра. Две двойные кавычки были добавлены потому, что OpenCover при вызове приложения xunit съедает одни из кавычек, а вторые кавычки нужны на случай наличия пробелов в абсолютных путях.

Следующая строка запуск утилиты OpenConver с передачей ей списка библиотек нашего приложения, фильтра, по которому OpenCover исключает из покрытия библиотеки с unit-тестами, а также часть классов, не требующих расчёта покрытия (например, AssemblyInfo). Конвейер и Write-Host были добавлены в порыве вдохновения, так как без него у нас не работал вывод OpenConver-а.

И следующий if проверяет, успешно ли завершился запуск OpenConver. Если не успешно кладём скрипт; если же успешно парсим получившийся xml-файлик с отчётом и печатаем значения покрытия тестами, чтобы затем его легко распарсил gitlab через указанное в настройках регулярное выражение.

Послесловие

Как известно, нет предела совершенству. Мы продолжим добавлять новые функции в используемые нами процессы сборки, тестирования и публикации. На момент написания тестируется переезд нашего ПО на .NET 5 (с ним OpenCover уже не работает, сборка выполняется через команду dotnet), а также мы переходим на другой способ публикации (к сожалению, пока не могу дать более подробный комментарий).

Если у вас появятся вопросы или предложения пишите в комментариях.

И спасибо за прочтение!

Из-за прекращения поддержи Bitbucket Setver пришлось переехать на GitLab.

В Bitbucket Server не было встроенного CI/CD, поэтому использовали Teamcity. Из-за проблемы интеграции Teamcity с GitLab, мы попробовали GitLab Pipline. И остались довольны.

Disclamer: У меня не так много опыта в CI/CD, так что статья скорее для новичков. Буду рад услышать конструктивную критику с предложениями по оптимизации скрипта сборки :)

Коротко о Gitlab Pipline

Если говорить простыми словами: сборка делится на задачи. Какие-то задачи выполняются последовательно и передают результаты следующим задачам, какие-то задачи распаралеливаются: например можно одновременно деплоить на сервер и в nexus.

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

Раннеры бывают разных типов. Мы рассмотрим executor docker. Для каждой задачи создается новый чистый контейнер. Но между контейнерами можно передавать промежуточные результаты это называется кэширование.

Кэширование и его особенности

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

Каждый раннер хранит кэш в папке /cache. Для каждого проекта в этой папке создается еще папка. Сам кэш хранится в виде zip архива.

Из-за наличия у каждого раннера своей папки для кэша, возникает проблема. Если один раннер кэшировал папку в первой задаче, а второй раннер взялся за выполнение второй задачи, то у него не окажется кэша из первой задачи. Чуть далее рассмотрим как это исправить.

Можно определить только один набор папок для кэша. Также только для всего набора можно выбрать политику кэширования. Например если вы уверены, что задача не изменит кэш, то можно его не загружать. Но нельзя запретить загружать например две папки из четырех.

Нет возможности установить глобальный кэш и добавить к нему дополнительные папки для конкретных задач.

Так же стоит знать, что кэш не удаляется после окончания сборки. При следующей такой же сборке старый кэш будет доступен.

Эти особенности усложняют создание инструкций для CI CD.

Артефакты

Помимо кэша между сборками можно передавать артефакты.

Артефакт это файлы, которые считаются законченным продуктом сборки. Например .jar файлы приложения.

В отличие от кэша, артефакт передается между раннерами. Из-за этого многие злоупотребляют использованием артефактов там, где стоит использовать кэш.

Следуйте следующим правилам:

1. Если текущее задание может выполняться самостоятельно, но в присутствии контента работа будет идти быстрее, используйте кэш.
2. Если текущее задание зависит от результатов предыдущего, то есть не может выполняться само по себе, используйте артефакты и зависимости.

Установка Gitlab Runner

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

mkdir ~/runner_name

Само создание ранера выполняется в одну команду. Можно создать сколько угодно ранеров.

docker run -d --name gitlab-runner-name \  --restart always \  -v /var/run/docker.sock:/var/run/docker.sock \  -v /home/user/runner_name:/etc/gitlab-runner:z \  gitlab/gitlab-runner:latest

Мало создать раннер, теперь его нужно зарегистрировать в GitLab. Зарегистрировать можно на уровне всего GitLab, тогда сборки будут выполняться для любого проекта; на уровне группы выполнятся только для группы, и на уровне проекта.

Заходим в контейнер.

sudo docker exec -ti gitlab-runner-name bash

Внутри контейнера выполним команду регистрации. Регистрация происходит в интерактивном режиме.

gitlab-runner register

Отвечаем на вопросы:

Runtime platform                                    arch=amd64 os=linux pid=27 revision=888ff53t version=13.8.0Running in system-mode.                            Enter the GitLab instance URL (for example, https://gitlab.com/):http://git.company.name/Enter the registration token:vuQ6bcjuEPqc8dVRRhgYEnter a description for the runner:[c6558hyonbri]: runner_twoEnter tags for the runner (comma-separated):Registering runner... succeeded                     runner=YJt3v3QgEnter an executor: parallels, shell, virtualbox, docker+machine, kubernetes, custom, docker, docker-ssh+machine, docker-ssh, ssh:dockerEnter the default Docker image (for example, ruby:2.6):maven:3.3.9-jdk-8Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! 

Тут все просто:

1. Адрес вашего gitlab.
2. Токен авторизации. Посмотреть его можно в настройках гурппы/проекта в разделе CI/CD Runners.
3. Название раннера.
4. Теги ранера, можно пропустить нажав Enter.
5. Исполнитель сборки. Вводим docker.
6. Образ, который будет использоваться по умолчанию, если не установлен другой.

После этого в настройках проекта можно посмотреть доступные раннеры.

После регистрации, в папке /home/user/runner_name появится файл с настройками конфигурации config.toml. Нам нужно добавить docker volume для кэширования промежуточных результатов.

volumes = ["gitlab-runner-builds:/builds", "gitlab-runner-cache:/cache"]

Проблема кэширования.
В начале статьи я рассказал о проблеме кеширования. Ее можно решить с помощью монтирования одного volume к разным раннерам. То есть во втором своем раннере так же укажите volumes = ["gitlab-runner-cache:/cache"]. Таким образом разные раннеры будут иметь единый кэш.

В итоге файл конфигурации выглядит так:

concurrent = 1check_interval = 0[session_server]  session_timeout = 1800[[runners]]  name = "runner_name"  url = "gitlab_url"  token = "token_value"  executor = "docker"  [runners.custom_build_dir]  [runners.cache]    [runners.cache.s3]    [runners.cache.gcs]    [runners.cache.azure]  [runners.docker]    tls_verify = false    image = "maven:3.3.9-jdk-8"    privileged = false    disable_entrypoint_overwrite = false    oom_kill_disable = false    disable_cache = false    volumes = ["gitlab-runner-builds:/builds", "gitlab-runner-cache:/cache"]    shm_size = 0

После изменения перезапускаем раннер.

docker restart gitlab-runner-name

Что хотим получить от CI CD?

У нас на проекте было 3 контура:

• dev-сервер, на него все попадает сразу после MR;
• пре-прод-сервер, на него все попадает перед попаданием на прод, там проходит полное регресс тестирование;
• прод-сервер, собственно сама прод среда.

Что нам было необходимо от нашего CI/CD:

• Запуск unit-тестов для всех MergeRequest
• При мерже в dev ветку повторный запуск тестов и автоматический деплой на dev-сервер.
• Автоматическая сборка, тестирвоание и деплой веток формата release/* на пре-прод-сервер.
• При мерже в master ничего не происходит. Релиз собирается при обнаружении тега формата release-*. Одновременно с деплоем на прод-сервер будет происходить загрузка в корпоративный nexus.
• Бонусом настроим уведомления о статусе деплоя в Telegram.

Настройка GitLab CI для Maven

Что делать если у вас Gradle? Загляните в оригинал статьи, там я рассказываю про настройку и для Gradle. Она не сильно отличается.

Создайте в корне проекта файл .gitlab-ci.yml.

Настройку буду объяснять блоками, в конце прикреплю единый файл.

Вы можете указать нужный образ, вместо дефолтного образа у раннера.

image: maven:latest

Устанавливаем место хранения папки .m2 через переменные среды variables. Это понадобится, когда будем настраивать кэширование.

// ... ... ... ... ...variables:  MAVEN_OPTS: "-Dmaven.repo.local=./.m2/repository"// ... ... ... ... ...

Далее указываются этапы сборки. Они позволяют группировать задачи для одновременного выполнения.

// ... ... ... ... ...stages:  - build  - test  - package  - deploy  - notify// ... ... ... ... ...

• build стадия сборки.
• test стадия тестирования.
• package стадия упаковки в jar.
• deploy стадия деплоя на сервер.
• notify стадия уведомления о провале.

Указываем непосредственно задачи для каждой стадии.

Сборка Build

// ... ... ... ... ...build:  stage: build  only:    - dev    - merge_requests    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS compile'  cache:    paths:      - ./target      - ./.m2// ... ... ... ... ...

Раздел script выполняет linux команды.

Переменная GitLab CI/CD $MAVEN_SETTINGS необходима для передачи файла settings.xml, если вы используете нестандартные настройки, например корпоративные репозитории. Переменная создается в настройках CI/CD для группы/проекта. Тип переменной File.

Раздел only указывает для каких веток и тегов выполнять задачу. Чтобы не собирать каждую запушенную ветку устанавливаем: dev, merge_requests и ветки формата /release/*.

Раздел only не разделяет ветка это или тег. Поэтому мы указываем параметр except, который исключает теги. Из-за этого поведения за сборку на прод отвечают отдельные задачи. В противном случае, если бы кто-то создал тег формата release/*, то он бы запустил сборку.

Для защиты от случайного деплоя в прод джуном, рекомендую установить защиту на ветки dev, master, /release/*, а так же на теги release-*. Делается это в настройках проекта GitLab.

Раздел cache отвечает за кэширование. Чтобы каждый раз не выкачивать зависимости добавляем в кэш папку ./target и ./.m2.

Запуск unit тестов test

Создаем задачу для запука тестирования.

// ... ... ... ... ...test:  stage: test  only:    - dev    - merge_requests    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS test'  cache:    paths:      - ./target      - ./.m2// ... ... ... ... ...

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

Упаковка package

Следом добавляем задачу упаковки с выключенными тестами. Она уже выполняется только для веток dev и release/*. Упаковывать Merge Request смысла нет.

// ... ... ... ... ...package:  stage: package  only:    - dev    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS package -Dmaven.test.skip=true'  artifacts:    paths:      - target/*.jar  cache:    policy: pull    paths:      - ./target      - ./.m2// ... ... ... ... ...

Обратите внимание на policy: pull и artifacts. В следующих задачах не нужны исходники и зависимости, так что policy: pull отключает кэширование. Для сохранения результатов сборки используем artifacts, который сохраняет .jar файлы и передает их следующим задачам.

Деплой deploy

Теперь осталось задеплоить артефакт на dev-сервер с помощью ssh и scp.

// ... ... ... ... ...deploy_dev_server:  stage: deploy  only:    - dev  except:    - tags  before_script:    - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )    - eval $(ssh-agent -s)    - echo "$SSH_PRIVATE_KEY" | ssh-add -    - mkdir -p ~/.ssh    - chmod 700 ~/.ssh    - ssh-keyscan $DEV_HOST >> ~/.ssh/known_hosts    - chmod 644 ~/.ssh/known_hosts  script:    - ssh $DEV_USER@$DEV_HOST "[ ! -f $DEV_APP_PATH/app_name.jar ] || mv $DEV_APP_PATH/app_name.jar $DEV_APP_PATH/app_name-build-$CI_PIPELINE_ID.jar"    - scp target/app_name.jar $DEV_USER@$DEV_HOST:$DEV_APP_PATH/    - ssh $DEV_USER@$DEV_HOST "sudo systemctl stop app_name_service && sudo systemctl start app_name_service"    - sh ci-notify.sh // ... ... ... ... ...

Не забудьте создать переменные в GitLab CI CD:

• $DEV_USER пользователь системы, от чьего имени будет происходить деплой.
• $DEV_HOST ip адрес сервера.
• $DEV_APP_PATH путь до папки приложения.
• $SSH_PRIVATE_KEY приватный ключ.

Раздел before_script отвечает за выполнение настроек перед основным скриптом. Мы проверяем наличие ssh-agent, устанавливаем его при отсутствии. После чего добавляем приватный ключ, устанавливаем правильные права на папки.

В разделе script происходит деплой на сервер:

1. Проверяем наличие старого jar и переименовываем его. $CI_PIPELINE_ID это глобальный номер сборки Pipeline.
2. Копируем новый jar на сервер.
3. Останавливаем и запускаем службу, отвечающую за приложение.
4. Отправляем уведомление об успехе в телеграм. Об этом ниже.

Как создавать службы linux для Spring Boot приложения, я написал в отдельной статье.

На пре-прод делаем по аналогии, только меняем переменные на $PRE_PROD_*.

// ... ... ... ... ...deploy_pre_prod:  stage: deploy  only:    - /^release\/.*$/  except:    - tags  before_script:    - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )    - eval $(ssh-agent -s)    - echo "$SSH_PRIVATE_KEY" | ssh-add -    - mkdir -p ~/.ssh    - chmod 700 ~/.ssh    - ssh-keyscan $PRE_PROD_HOST >> ~/.ssh/known_hosts    - chmod 644 ~/.ssh/known_hosts  script:    - ssh $PRE_PROD_USER@$PRE_PROD_HOST "[ ! -f $PRE_PROD_APP_PATH/app_name.jar ] || mv $PRE_PROD_APP_PATH/app_name.jar $PRE_PROD_APP_PATH/app_name-build-$CI_PIPELINE_ID.jar"    - scp target/app_name.jar $DEV_USER@$PRE_PROD_HOST:$PRE_PROD_APP_PATH/    - ssh $PRE_PROD_USER@$PRE_PROD_HOST "sudo systemctl stop app_name_service && sudo systemctl start app_name_service"    - sh ci-notify.sh // ... ... ... ... ...

Настройка деплоя на прод

Для прод-деплоя можно объединить сборку, тестирование и упаковку в одну задачу.

// ... ... ... ... ...package_prod:  stage: package  only:    - /^release-.*$/  except:    - branches  script:    - 'mvn --settings $MAVEN_SETTINGS package'  artifacts:    paths:      - target/*.jar// ... ... ... ... ...

Мы защищаемся от срабатывания на ветки формата release-*, нам нужно срабатывание только по тегу.

Деплой аналогичен пре-проду, изменяется только only и переменные.

Дополнительно появляется задача с отправкой артефакта в корпоративный nexus. Деплой на сервер и в нексус работает параллельно.

// ... ... ... ... ...deploy_prod:  stage: deploy  only:    - /^release-.*$/  except:    - branches  ...deploy_nexus_server:  stage: deploy  only:    - /^release-.*$/  except:    - branches  script:    - 'mvn --settings $MAVEN_SETTINGS deploy -Dmaven.test.skip=true'// ... ... ... ... ...

Итоговый .gitlab-ci.yml:

image: maven:latestvariables:  MAVEN_OPTS: "-Dmaven.repo.local=./.m2/repository"stages:  - build  - test  - package  - deploy  - notifybuild:  stage: build  only:    - dev    - merge_requests    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS compile'  cache:    paths:      - ./target      - ./.m2test:  stage: test  only:    - dev    - merge_requests    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS test'  cache:    paths:      - ./target      - ./.m2package:  stage: package  only:    - dev    - /^release\/.*$/  except:    - tags  script:    - 'mvn --settings $MAVEN_SETTINGS package -Dmaven.test.skip=true'  artifacts:    paths:      - target/*.jar  cache:    policy: pull    paths:      - ./target      - ./.m2deploy_dev_server:  stage: deploy  only:    - dev  except:    - tags  before_script:    - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )    - eval $(ssh-agent -s)    - echo "$SSH_PRIVATE_KEY" | ssh-add -    - mkdir -p ~/.ssh    - chmod 700 ~/.ssh    - ssh-keyscan $DEV_HOST >> ~/.ssh/known_hosts    - chmod 644 ~/.ssh/known_hosts  script:    - ssh $DEV_USER@$DEV_HOST "[ ! -f $DEV_APP_PATH/app_name.jar ] || mv $DEV_APP_PATH/app_name.jar $DEV_APP_PATH/app_name-build-$CI_PIPELINE_ID.jar"    - scp target/app_name.jar $DEV_USER@$DEV_HOST:$DEV_APP_PATH/    - ssh $DEV_USER@$DEV_HOST "sudo systemctl stop app_name_service && sudo systemctl start app_name_service"deploy_pre_prod:  stage: deploy  only:    - /^release\/.*$/  except:    - tags  before_script:    - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )    - eval $(ssh-agent -s)    - echo "$SSH_PRIVATE_KEY" | ssh-add -    - mkdir -p ~/.ssh    - chmod 700 ~/.ssh    - ssh-keyscan $PRE_PROD_HOST >> ~/.ssh/known_hosts    - chmod 644 ~/.ssh/known_hosts  script:    - ssh $PRE_PROD_USER@$PRE_PROD_HOST "[ ! -f $PRE_PROD_APP_PATH/app_name.jar ] || mv $PRE_PROD_APP_PATH/app_name.jar $PRE_PROD_APP_PATH/app_name-build-$CI_PIPELINE_ID.jar"    - scp target/app_name.jar $DEV_USER@$DEV_HOST:$DEV_APP_PATH/    - ssh $PRE_PROD_USER@$PRE_PROD_HOST "sudo systemctl stop app_name_service && sudo systemctl start app_name_service"package_prod:  stage: package  only:    - /^release-.*$/  except:    - branches  script:    - 'mvn --settings $MAVEN_SETTINGS package'  artifacts:    paths:      - target/*.jardeploy_prod:  stage: deploy  only:    - /^release-.*$/  except:    - branches  before_script:    - which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )    - eval $(ssh-agent -s)    - echo "$SSH_PRIVATE_KEY" | ssh-add -    - mkdir -p ~/.ssh    - chmod 700 ~/.ssh    - ssh-keyscan $PROD_HOST >> ~/.ssh/known_hosts    - chmod 644 ~/.ssh/known_hosts  script:    - ssh $PROD_USER@$PROD_HOST "[ ! -f $PROD_APP_PATH/app_name.jar ] || mv $PROD_APP_PATH/app_name.jar $PROD_APP_PATH/app_name-build-$CI_PIPELINE_ID.jar"    - scp target/app_name.jar $PROD_USER@$PROD_HOST:$PROD_APP_PATH/    - ssh $PROD_USER@$PROD_HOST "sudo systemctl stop app_name_service && sudo systemctl start app_name_service"

Бонус: уведомления о деплое в Telegram

Полезная фишка для уведомления менеджеров. После сборки в телеграм отправляется статус сборки, название проекта и ветка сборки.

В задачах деплоя последней командой пропишите:

// ... ... ... ... ...script:  - ...  - sh ci-notify.sh // ... ... ... ... ...

Сам файл необходимо добавить в корень проекта, рядом с файлом .gitlab-ci.yml.

Содержимое файла:

#!/bin/bashTIME="10"URL="http://personeltest.ru/aways/api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage"TEXT="Deploy status: $1%0A-- -- -- -- --%0ABranch:+$CI_COMMIT_REF_SLUG%0AProject:+$CI_PROJECT_TITLE"curl -s --max-time $TIME -d "chat_id=$TELEGRAM_CHAT_ID&disable_web_page_preview=1&text=$TEXT" $URL >/dev/null

Скрипт отправляет запрос к API Telegram, через curl. Параметром скрипта передается emoji статуса билда.

Не забудьте добавить новые параметры в CI/CD:

• $TELEGRAM_BOT_TOKEN токен бота в телеграмм. Получить его можно при создании своего бота.
• $TELEGRAM_CHAT_ID идентификатор чата или беседы, в которую отправляется сообщение. Узнать идентификатор можно с помощью специального бота.

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

// ... ... ... ... ...notify_error:  stage: notify  only:    - dev    - /^release\/.*$/  script:    - sh ci-notify.sh   when: on_failurenotify_error_release:  stage: notify  only:    - /^release-.*$/  except:    - branches  script:    - sh ci-notify.sh   when: on_failure// ... ... ... ... ...

По сложившейся традиции у нас отдельная задача для прод-среды. Благодаря параметру when: on_failure задача отрабатывает только, когда одна из предыдущих завершилась неудачно.

Удобно, что теперь и код и сборка находятся в одном месте. Несмотря на недостатки GitLab CI, пользоваться им в целом удобно.