🥇Ръководство за CI/CD в GitLab за (почти) абсолютен начинаещ

Или как да получите красиви значки за вашия проект за една вечер на лесно кодиране

Вероятно всеки разработчик, който има поне един домашен проект, в даден момент изпитва сърбеж по красиви значки със статуси, покритие на кода, версии на пакети в nuget ... И този сърбеж ме накара да напиша тази статия. Подготвяйки се да го напиша, получих тази красота в един от моите проекти:

Тази статия ще ви преведе през основната настройка на непрекъсната интеграция и доставка за проект на библиотека от класове .Net Core в GitLab, публикуване на документация в GitLab Pages и изпращане на изградени пакети към частна емисия в Azure DevOps.

VS Code беше използван като среда за разработка с разширението Работен процес на GitLab (за валидиране на файла с настройки директно от средата за разработка).

Кратко въведение

CD - това е, когато просто бутнете и всичко вече е паднало върху клиента?

Какво е CI / CD и защо ви трябва - можете лесно да го потърсите в Google. Намерете пълна документация за конфигуриране на конвейери в GitLab също лесно. Тук накратко и, ако е възможно, без недостатъци ще опиша процеса на системата от птичи поглед:

разработчикът изпраща ангажимент към хранилището, създава заявка за сливане през сайта, или по някакъв друг начин, изрично или имплицитно стартира тръбопровода,
всички задачи се избират от конфигурацията, чиито условия позволяват да бъдат стартирани в даден контекст,
задачите са организирани според техните етапи,
етапите се изпълняват на свой ред - т.е. паралелно всички задачи от този етап са изпълнени,
ако етапът се провали (т.е. поне една от задачите на етапа се провали), конвейерът спира (почти винаги),
ако всички етапи са завършени успешно, тръбопроводът се счита за успешен.

Така имаме:

тръбопровод - набор от задачи, организирани на етапи, в които можете да изграждате, тествате, пакетирате код, внедрявате завършена компилация в облачна услуга и т.н.,
сцена (етап) — организационна единица за конвейер, съдържа 1+ задача,
задача (работа) е единица работа в конвейера. Състои се от скрипт (задължителен), условия за стартиране, настройки за публикуване/кеширане на артефакти и много други.

Съответно, задачата при настройка на CI / CD се свежда до създаване на набор от задачи, които изпълняват всички необходими действия за изграждане, тестване и публикуване на код и артефакти.

Преди да започнете: защо?

Защо Gitlab?

Защото, когато стана необходимо да се създадат частни хранилища за проекти за домашни любимци, те бяха платени в GitHub и аз бях алчен. Репозиториите станаха безплатни, но засега това не е достатъчна причина да се преместя в GitHub.

Защо не Azure DevOps тръбопроводи?

Защото там настройката е елементарна - дори не се изисква познаване на командния ред. Интеграция с външни доставчици на git - с няколко щраквания, импортиране на SSH ключове за изпращане на ангажименти към хранилището - също конвейерът се конфигурира лесно дори не от шаблон.

Начална позиция: това, което имате и това, което искате

Имаме:

хранилище в GitLab.

Ние искаме:

автоматично сглобяване и тестване за всяка заявка за сливане,
изграждане на пакети за всяка заявка за сливане и насочване към главния, при условие че има определен ред в съобщението за ангажиране,
изпращане на изградени пакети към частна емисия в Azure DevOps,
събиране на документация и публикуване в GitLab Pages,
значки!11

Описаните изисквания органично попадат върху следния модел на тръбопровода:

Етап 1 - Сглобяване
- Ние събираме кода, публикуваме изходните файлове като артефакти
Етап 2 - тестване
- Получаваме артефакти от етапа на изграждане, провеждаме тестове, събираме данни за покритието на кода
Етап 3 - Изпращане
- Задача 1 - изградете пакета nuget и го изпратете на Azure DevOps
- Задача 2 - събираме сайта от xmldoc в изходния код и го публикуваме в GitLab Pages

Да започнем!

Събиране на конфигурацията

Изготвяне на сметки

Създайте акаунт в Microsoft Azure
Отидете на Azure DevOps
Създаваме нов проект
1. Име - всяко
2. Видимост - всякаква
Когато щракнете върху бутона Създаване, проектът ще бъде създаден и ще бъдете пренасочени към неговата страница. На тази страница можете да деактивирате ненужните функции, като отидете в настройките на проекта (долната връзка в списъка вляво -> Общ преглед -> Блок за услуги на Azure DevOps)
Отидете на Atrifacts, щракнете върху Създаване на емисия
1. Въведете името на източника
2. Изберете видимост
3. Премахнете отметката Включете пакети от общи публични източници, така че източникът да не се превърне в dump nuget клонинг
Щракнете върху Connect to feed, изберете Visual Studio, копирайте Source от блока Machine Setup
Отидете в настройките на акаунта, изберете Personal Access Token
Създайте нов маркер за достъп
1. Име - произволно
2. Организация - Текуща
3. Валиден за максимум 1 година
4. Обхват - Опаковка/Четене и писане
Копирайте създадения токен - след затваряне на модалния прозорец стойността няма да бъде налична
Отидете до настройките на хранилището в GitLab, изберете настройките за CI / CD
Разширете блока Променливи, добавете нов
1. Име - всяко без интервали (ще бъде налично в командната обвивка)
2. Стойност - маркер за достъп от параграф 9
3. Изберете променлива маска

Това завършва предварителната конфигурация.

Подготовка на конфигурационната рамка

По подразбиране конфигурацията на CI/CD в GitLab използва файла .gitlab-ci.yml от корена на хранилището. Можете да зададете произволен път до този файл в настройките на хранилището, но в този случай не е необходимо.

Както можете да видите от разширението, файлът съдържа конфигурация във формат YAML. Документацията описва кои ключове могат да се съдържат на най-високото ниво на конфигурацията и на всяко от вложените нива.

Първо, нека добавим връзка към докер изображението в конфигурационния файл, в който ще се изпълняват задачите. За това намираме Страница с изображения на .Net Core в Docker Hub. В GitHub има подробно ръководство за това кое изображение да изберете за различни задачи. Изображение с .Net Core 3.1 е подходящо за изграждане, така че не се колебайте да добавите първия ред към конфигурацията

image: mcr.microsoft.com/dotnet/core/sdk:3.1

Сега, когато конвейерът се стартира от хранилището на изображения на Microsoft, ще бъде изтеглено посоченото изображение, в което ще се изпълняват всички задачи от конфигурацията.

Следващата стъпка е да добавите етап'с. По подразбиране GitLab дефинира 5 етапа:

.pre - изпълнени до всички етапи,
.post - извършва се след всички етапи,
build - първо след .pre сцена,
test - втора фаза,
deploy - третият етап.

Нищо не пречи обаче да ги декларирате изрично. Редът, в който са изброени стъпките, влияе върху реда, в който се изпълняват. За пълнота нека добавим към конфигурацията:

stages:
  - build
  - test
  - deploy

За отстраняване на грешки има смисъл да получите информация за средата, в която се изпълняват задачите. Нека добавим глобален набор от команди, които ще се изпълняват преди всяка задача с before_script:

before_script:
  - $PSVersionTable.PSVersion
  - dotnet --version
  - nuget help | select-string Version

Остава да добавим поне една задача, за да може при изпращане на комитите да тръгне конвейера. Засега нека добавим празна задача, за да демонстрираме:

dummy job:
  script:
    - echo ok

Започваме валидиране, получаваме съобщение, че всичко е наред, ангажираме се, натискаме, гледаме резултатите на сайта ... И получаваме грешка в скрипта - bash: .PSVersion: command not found. wtf?

Всичко е логично - по подразбиране runners (отговорни за изпълнението на скриптове на задачи и предоставени от GitLab) използват bash за изпълнение на команди. Можете да поправите това, като изрично посочите в описанието на задачата какви тагове трябва да има изпълняващият се конвейер:

dummy job on windows:
  script:
    - echo ok
  tags:
    - windows

Страхотен! Тръбопроводът вече работи.

Внимателният читател, след като повтори посочените стъпки, ще забележи, че задачата е изпълнена в етапа test, въпреки че не уточнихме етапа. Както се досещате test е стъпката по подразбиране.

Нека продължим да създаваме конфигурационния скелет, като добавим всички задачи, описани по-горе:

build job:
  script:
    - echo "building..."
  tags:
    - windows
  stage: build

test and cover job:
  script:
    - echo "running tests and coverage analysis..."
  tags:
    - windows
  stage: test

pack and deploy job:
  script:
    - echo "packing and pushing to nuget..."
  tags:
    - windows
  stage: deploy

pages:
  script:
    - echo "creating docs..."
  tags:
    - windows
  stage: deploy

Получихме не особено функционален, но въпреки това правилен тръбопровод.

Настройка на тригери

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

Филтрите могат да бъдат конфигурирани в два формата: само/освен и правилник. накратко only/except ви позволява да конфигурирате филтри по тригери (merge_request, например - задава задачата да се изпълнява всеки път, когато се създава заявка за изтегляне и всеки път, когато се изпращат ангажименти към клона, който е източникът в заявката за сливане) и имена на клонове (включително използване на регулярни изрази); rules ви позволява да персонализирате набор от условия и по желание да промените условието за изпълнение на задачата в зависимост от успеха на предишни задачи (when в GitLab CI/CD).

Нека си припомним набор от изисквания - асемблиране и тестване само за заявка за сливане, опаковане и изпращане до Azure DevOps - за заявка за сливане и натискане към главния, генериране на документация - за насочвания към главния.

Първо, нека настроим задачата за изграждане на код, като добавим правило, което се задейства само при заявка за сливане:

build job:
  # snip
  only:
    - merge_request

Сега нека настроим задачата за опаковане да задейства заявката за сливане и да добавим ангажименти към главния:

pack and deploy job:
  # snip
  only:
    - merge_request
    - master

Както можете да видите, всичко е просто и ясно.

Можете също така да настроите задачата да се задейства само ако е създадена заявка за сливане с конкретен целеви или изходен клон:

  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"

При условия можете да използвате променливи, изброени тук; правила rules несъвместими с правилата only/except.

Конфигуриране на запазване на артефакт

По време на задача build job ще имаме артефакти за изграждане, които могат да бъдат използвани повторно в следващите задачи. За да направите това, трябва да добавите пътищата към конфигурацията на задачата, файловете, по които ще трябва да запазите и използвате повторно в следващите задачи, към ключа artifacts:

build job:
  # snip
  artifacts:
    paths:
      - path/to/build/artifacts
      - another/path
      - MyCoolLib.*/bin/Release/*

Пътищата поддържат заместващи символи, което определено ги прави по-лесни за задаване.

Ако дадена задача създава артефакти, тогава всяка следваща задача ще има достъп до тях - те ще бъдат разположени по същите пътища спрямо корена на хранилището, които са събрани от оригиналната задача. Артефактите също са достъпни за изтегляне на сайта.

Сега, след като имаме готова (и тествана) конфигурационна рамка, можем да пристъпим към реално писане на скриптове за задачи.

Ние пишем сценарии

Може би някога, в една далечна, далечна галактика, изграждането на проекти (включително тези в .net) от командния ред е било болка. Сега можете да изградите, тествате и публикувате проекта в 3 екипа:

dotnet build
dotnet test
dotnet pack

Естествено, има някои нюанси, поради които ще усложним донякъде командите.

Искаме компилация за освобождаване, а не компилация за отстраняване на грешки, така че добавяме към всяка команда -c Release
Когато тестваме, искаме да събираме данни за покритието на кода, така че трябва да включим анализатор на покритие в тестовите библиотеки:
1. Добавете пакета към всички тестови библиотеки coverlet.msbuild: dotnet add package coverlet.msbuild от папката на проекта
2. Добавете към командата за тестово изпълнение /p:CollectCoverage=true
3. Добавете ключ към конфигурацията на тестовата задача, за да получите резултати от покритието (вижте по-долу)
Когато опаковате кода в nuget пакети, задайте изходната директория за пакетите: -o .

Събиране на данни за покритието на кода

След провеждане на тестовете, Coverlet отпечатва статистика за изпълнение на конзолата:

Calculating coverage result...
  Generating report 'C:Usersxxxsourcereposmy-projectmyProject.testscoverage.json'

+-------------+--------+--------+--------+
| Module      | Line   | Branch | Method |
+-------------+--------+--------+--------+
| project 1   | 83,24% | 66,66% | 92,1%  |
+-------------+--------+--------+--------+
| project 2   | 87,5%  | 50%    | 100%   |
+-------------+--------+--------+--------+
| project 3   | 100%   | 83,33% | 100%   |
+-------------+--------+--------+--------+

+---------+--------+--------+--------+
|         | Line   | Branch | Method |
+---------+--------+--------+--------+
| Total   | 84,27% | 65,76% | 92,94% |
+---------+--------+--------+--------+
| Average | 90,24% | 66,66% | 97,36% |
+---------+--------+--------+--------+

GitLab ви позволява да посочите регулярен израз, за да получите статистика, която след това може да бъде получена под формата на значка. Регулярният израз е зададен в настройките на задачата с ключа coverage; изразът трябва да съдържа група за улавяне, чиято стойност ще бъде предадена на значката:

test and cover job:
  # snip
  coverage: /|s*Totals*|s*(d+[,.]d+%)/

Тук получаваме статистика от линия с пълно покритие на линията.

Публикувайте пакети и документация

И двете действия са планирани за последния етап от конвейера - тъй като монтажът и тестовете са преминали, можем да споделим нашите разработки със света.

Първо, помислете за публикуване в източника на пакета:

Ако проектът няма конфигурационен файл на nuget (nuget.config), създайте нов: dotnet new nugetconfig

Защо: изображението може да няма достъп за запис до глобални (потребителски и машинни) конфигурации. За да не улавяме грешки, ние просто създаваме нова локална конфигурация и работим с нея.
Нека добавим нов източник на пакет към локалната конфигурация: nuget sources add -name <name> -source <url> -username <organization> -password <gitlab variable> -configfile nuget.config -StorePasswordInClearText
1. name - име на локален източник, не е критично
2. url - URL на източника от етап "Изготвяне на сметки", стр. 6
3. organization - име на организация в Azure DevOps
4. gitlab variable - името на променливата с маркера за достъп, добавен към GitLab ("Подготовка на акаунти", стр. 11). Естествено във формат $variableName
5. -StorePasswordInClearText - хак за заобикаляне на грешката отказан достъп (Не съм първият, който стъпва на това гребло)
6. В случай на грешки може да е полезно да добавите -verbosity detailed
Изпращане на пакета до източника: nuget push -source <name> -skipduplicate -apikey <key> *.nupkg
1. Изпращаме всички пакети от текущата директория, така че *.nupkg.
2. name - от горната стъпка.
3. key - всяка линия. В Azure DevOps, в прозореца Свързване към канал, примерът винаги е редът az.
4. -skipduplicate - при опит за изпращане на вече съществуващ пакет без този ключ източникът ще върне грешка 409 Conflict; с ключа изпращането ще бъде пропуснато.

Сега нека настроим създаването на документация:

Първо, в хранилището, в главния клон, инициализираме проекта docfx. За да направите това, изпълнете командата от root docfx init и интерактивно задайте ключовите параметри за строителна документация. Подробно описание на минималната настройка на проекта тук.
1. Когато конфигурирате, е важно да посочите изходната директория ..public - GitLab по подразбиране взема съдържанието на публичната папка в корена на хранилището като източник за страници. защото проектът ще бъде разположен в папка, вложена в хранилището - добавете изход към нивото нагоре в пътя.
Нека изпратим промените в GitLab.
Добавете задача към конфигурацията на тръбопровода pages (запазена дума за задачи за публикуване на сайтове в GitLab Pages):
1. Скрипт:
  1. nuget install docfx.console -version 2.51.0 - инсталирайте docfx; версията е посочена, за да се гарантира, че пътищата за инсталиране на пакета са правилни.
  2. .docfx.console.2.51.0toolsdocfx.exe .docfx_projectdocfx.json - събиране на документация
2. Артефакти на възел:

pages:
  # snip
  artifacts:
    paths:
      - public

Лирично отклонение за docfx

Преди това, когато настройвах проект, посочих източника на код за документацията като файл с решение. Основният недостатък е, че се създава документация и за тестови проекти. В случай, че това не е необходимо, можете да зададете тази стойност на възела metadata.src:

{
  "metadata": [
    {
      "src": [
        {
          "src": "../",
          "files": [
            "**/*.csproj"
          ],
          "exclude":[
            "*.tests*/**"
          ]
        }
      ],
      // --- snip ---
    },
    // --- snip ---
  ],
  // --- snip ---
}

metadata.src.src: "../" - отиваме едно ниво нагоре спрямо местоположението docfx.json, защото в шаблони търсенето в дървото на директориите не работи.
metadata.src.files: ["**/*.csproj"] - глобален модел, събираме всички C # проекти от всички директории.
metadata.src.exclude: ["*.tests*/**"] - глобален модел, изключете всичко от папки с .tests В заглавието

Междинна сума

Такава проста конфигурация може да бъде създадена само за половин час и няколко чаши кафе, което ще ви позволи да проверите дали кодът е изграден и тестовете преминават, да изградите нов пакет, да актуализирате документацията и да зарадвате окото с красиви значки в README на проекта с всяка заявка за сливане и изпращане до главния.

Краен .gitlab-ci.yml

image: mcr.microsoft.com/dotnet/core/sdk:3.1

before_script:
  - $PSVersionTable.PSVersion
  - dotnet --version
  - nuget help | select-string Version

stages:
  - build
  - test
  - deploy

build job:
  stage: build
  script:
    - dotnet build -c Release
  tags:
    - windows
  only:
    - merge_requests
    - master
  artifacts:
    paths:
      - your/path/to/binaries

test and cover job:
  stage: test
  tags:
    - windows
  script:
    - dotnet test -c Release /p:CollectCoverage=true
  coverage: /|s*Totals*|s*(d+[,.]d+%)/
  only:
    - merge_requests
    - master

pack and deploy job:
  stage: deploy
  tags:
    - windows
  script:
    - dotnet pack -c Release -o .
    - dotnet new nugetconfig
    - nuget sources add -name feedName -source https://pkgs.dev.azure.com/your-organization/_packaging/your-feed/nuget/v3/index.json -username your-organization -password $nugetFeedToken -configfile nuget.config -StorePasswordInClearText
    - nuget push -source feedName -skipduplicate -apikey az *.nupkg
  only:
    - master

pages:
  tags:
    - windows
  stage: deploy
  script:
    - nuget install docfx.console -version 2.51.0
    - $env:path = "$env:path;$($(get-location).Path)"
    - .docfx.console.2.51.0toolsdocfx.exe .docfxdocfx.json
  artifacts:
    paths:
      - public
  only:
    - master

Говорейки за значки

Заради тях все пак всичко е започнато!

Значки със състояния на тръбопроводи и покритие на кода са налични в GitLab в настройките на CI/CD в блока за тръбопроводи Gtntral:

Създадох значка с връзка към документацията на платформата щитове.io - там всичко е доста лесно, можете да създадете своя собствена значка и да я получите чрез заявка.

![Пример с Shields.io](https://img.shields.io/badge/custom-badge-blue)

Артефактите на Azure DevOps също ви позволяват да създавате значки за пакети с най-новата версия. За да направите това, в източника на сайта на Azure DevOps трябва да щракнете върху Създаване на значка за избрания пакет и да копирате маркирането на маркирането:

Добавяне на красота

Осветяване на общи фрагменти от конфигурация

Докато пишех конфигурацията и търсех в документацията, попаднах на интересна функция на YAML - повторно използване на фрагменти.

Както можете да видите от настройките на задачата, всички те изискват етикета windows в runner и се задействат, когато заявка за сливане е изпратена до master/created (с изключение на документация). Нека добавим това към фрагмента, който ще използваме повторно:

.common_tags: &common_tags
  tags:
    - windows
.common_only: &common_only
  only:
    - merge_requests
    - master

И сега можем да вмъкнем фрагмента, деклариран по-рано в описанието на задачата:

build job:
  <<: *common_tags
  <<: *common_only

Имената на фрагментите трябва да започват с точка, за да не се тълкуват като задача.

Версиране на пакети

При създаване на пакет компилаторът проверява превключвателите на командния ред, а при липсата им - файловете на проекта; когато намери възел Version, той приема неговата стойност като версията на изградения пакет. Оказва се, че за да изградите пакет с нова версия, трябва или да го актуализирате във файла на проекта, или да го подадете като аргумент на командния ред.

Нека добавим още един списък с желания - нека второстепенните две числа във версията да бъдат годината и датата на компилация на пакета и да добавим предварителни версии. Разбира се, можете да добавите тези данни към файла на проекта и да проверявате преди всяко изпращане - но можете също да го направите в конвейера, като събирате версията на пакета от контекста и я предавате през аргумента на командния ред.

Нека се съгласим, че ако съобщението за ангажиране съдържа ред като release (v./ver./version) <version number> (rev./revision <revision>)?, тогава ще вземем версията на пакета от този ред, ще я допълним с текущата дата и ще я подадем като аргумент на командата dotnet pack. При липса на линия просто няма да вземем пакета.

Следният скрипт решава този проблем:

# регулярное выражение для поиска строки с версией
$rx = "releases+(v.?|ver.?|version)s*(?<maj>d+)(?<min>.d+)?(?<rel>.d+)?s*((rev.?|revision)?s+(?<rev>[a-zA-Z0-9-_]+))?"
# ищем строку в сообщении коммита, передаваемом в одной из предопределяемых GitLab'ом переменных
$found = $env:CI_COMMIT_MESSAGE -match $rx
# совпадений нет - выходим
if (!$found) { Write-Output "no release info found, aborting"; exit }
# извлекаем мажорную и минорную версии
$maj = $matches['maj']
$min = $matches['min']
# если строка содержит номер релиза - используем его, иначе - текущий год
if ($matches.ContainsKey('rel')) { $rel = $matches['rel'] } else { $rel = ".$(get-date -format "yyyy")" }
# в качестве номера сборки - текущие месяц и день
$bld = $(get-date -format "MMdd")
# если есть данные по пререлизной версии - включаем их в версию
if ($matches.ContainsKey('rev')) { $rev = "-$($matches['rev'])" } else { $rev = '' }
# собираем единую строку версии
$version = "$maj$min$rel.$bld$rev"
# собираем пакеты
dotnet pack -c Release -o . /p:Version=$version

Добавяне на скрипт към задача pack and deploy job и наблюдавайте сглобяването на пакети стриктно в присъствието на даден низ в съобщението за ангажиране.

Общо

След като прекарахме около половин или един час в писане на конфигурацията, отстраняване на грешки в локалния PowerShell и, вероятно, няколко неуспешни стартирания, получихме проста конфигурация за автоматизиране на рутинни задачи.

Разбира се, GitLab CI / CD е много по-обширен и многостранен, отколкото може да изглежда след като прочетете това ръководство - това изобщо не е вярно. Дори там Auto DevOps епозволявайки

автоматично открива, изгражда, тества, внедрява и наблюдава вашите приложения

Сега плановете са да се конфигурира конвейер за внедряване на приложения в Azure, като се използва Pulumi и автоматично определяне на целевата среда, което ще бъде разгледано в следващата статия.

Източник: www.habr.com

Ръководство за CI/CD в GitLab за (почти) абсолютен начинаещ