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

Или как да се сдобием с красиви бейджове за проекта си за един вечен лесен кодинг.

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

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

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

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

CD — това е, когато ти просто пушваш, а при клиента вече всичко е паднало?

Какво е CI/CD и защо е необходимо — може лесно да се намери в интернет. Пълната документация относно настройката на пайплайни в GitLab също не е трудна за намиране. Тук накратко и по възможност без грешки ще опиша процеса на работа на системата от височината на птичия полет:разработчикът изпраща комит в репозитория, създава merge request през сайта,

• или по друг начин явно или неявно стартира пайплайн от конфигурацията се избират всички задачи, чиито условия позволяват да бъдат стартирани в дадения контекст,,
• задачите се организират в съответствие с етапите си,
• етапите последователно се изп изпълняват — т.е.
• паралелно се изпълняват всички задачи от този етап, ако етапът завърши неуспешно (т.е. ако поне една от задачите в етапа завърши неуспешно) — пайплайнът спира (
• почти винагиако всички етапи завършват успешно, пайплайнът се счита за успешно преминал.),
• Така получаваме:

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

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

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

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

• Защо GitLab?

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

• Защо не Azure DevOps Pipelines?

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

Изходна позиция: какво имаме и какво искаме

Имаме:

• репозитория в GitLab.

Искаме:

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

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

• Етап 1 — компилация
  • Компилираме кода, изходните файлове публикуваме като артефакти
• Етап 2 — тестване
  • Получаваме артефактите от етапа на компилация, търсим тестовете, събираме данни за покритие на кода
• Етап 3 — изпращане
  • Задача 1 — събираме nuget пакет и изпращаме в Azure DevOps
  • Задача 2 — събираме сайт от xmldoc в изходния код и публикуваме в GitLab Pages

Да започнем!

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

Подготвяме акаунтите

1. Създаваме акаунт в Microsoft Azure

2. Преминаваме в Azure DevOps

3. Създаваме нов проект

   1. Име — произволно
   2. Видимост — произволна
      

4. При натискане на бутона Create проектът ще бъде създаден и ще настъпи преход към неговата страница. На тази страница може да се изключат ненужни възможности, като се премине в настройките на проекта (долна връзка в списъка отляво -> Overview -> блок Azure DevOps Services)
   

5. Преход към Atrifacts, натискаме Create feed

   1. Въвеждаме име на източника
   2. Избираме видимост
   3. Отмятаме отметката Include packages from common public sources, за да не се превърне източникът в сметище клонинг на nuget
      

6. Натискаме Connect to feed, избираме Visual Studio, от блока Machine Setup копираме Source
   

7. Отиваме в настройките на акаунта, избираме Personal Access Token
   

8. Създаваме нов токен за достъп

   1. Име — произволно
   2. Организация — текущата
   3. Срок на действие — максимум 1 година
   4. Област на действие (scope) — Packaging/Read & Write
      

9. Копиране на създадения токен — след затваряне на модалния прозорец стойността ще бъде недостъпна

10. Влизаме в настройките на репозитория в GitLab, избираме настройките на CI/CD
    

11. Разширяваме блока Variables, добавяме нова

    1. Име — всяко без интервали (ще бъде достъпно в командния интерпретатор)
    2. Стойност — токен за достъп от т. 9
    3. Избираме Mask variable
       

На това предварителната настройка приключва.

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

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

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

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

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

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

Следващата стъпка — добавяне на stageетапи. По подразбиране 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: команда не е намерена. Какво по дяволите?

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

dummy job на 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 и rules. Накратко, only/except позволява настройка на филтри по тригери (merge_request, например — настройва задачата да се изпълнява при всяко създаване на заявка за сливане и при всяко изпращане на комити в клона, който е изходен в заявката за сливане) и по имена на клонове (в т.ч. с използване на регулярни изрази); rules позволява да се настройват набор от условия и, по желание, да се променя условието за изпълнение на задачата в зависимост от успеха на предшестващите задачи (в в GitLab CI/CD).

Нека припомним набора от изисквания — построяване и тестване само за merge request, опаковане и изпращане в Azure DevOps — за merge request и пушове в майсторския клон, генериране на документация — за пушове в майсторския клон.

За начало, нека настроим задачата за изграждане на код, като добавим правило за задействане само при merge request:

build job:
  # snip
  only:
    - merge_request

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

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

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

Можете да настроите задачата така, че да се изпълнява само ако е създаден merge request с определена целева или основна клонка:

  правила:
    - ако: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"

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

Настройка на запазването на артефакти

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

build job:
  # snip
  артефакти:
    пътища:
      - path/to/build/artifacts
      - another/path
      - MyCoolLib.*/bin/Release/*

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

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

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

Пишем скриптове

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

dotnet build
dotnet test
dotnet pack

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

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

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

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

Изчисляване на резултатите от покритието...
  Генериране на отчет 'C:Usersxxxsourcereposmy-projectmyProject.testscoverage.json'

+-------------+--------+--------+--------+
| Модул      | Линия | Клон   | Метод  |
+-------------+--------+--------+--------+
| проект 1   | 83,24% | 66,66% | 92,1%  |
+-------------+--------+--------+--------+
| проект 2   | 87,5%  | 50%    | 100%   |
+-------------+--------+--------+--------+
| проект 3   | 100%   | 83,33% | 100%   |
+-------------+--------+--------+--------+

+---------+--------+--------+--------+
|         | Линия | Клон   | Метод  |
+---------+--------+--------+--------+
| Общо    | 84,27% | 65,76% | 92,94% |
+---------+--------+--------+--------+
| Средно  | 90,24% | 66,66% | 97,36% |
+---------+--------+--------+--------+

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

работа по тестове и покритие:
  # съкращение
  покритие: /|s*Общосумарни*|s*(d+[,.]d+%)

Тук получаваме статистика от реда с общото покритие по линии.

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

И двете действия са насрочени за последния етап на пайплайна — след като изграждането и тестовете минаха, можем да споделим разработките си с света.

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

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

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

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

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

1. Първо, в репозиторито, в клон master, инициализираме проекта docfx. За това от кореновата директория трябва да изпълним командата docfx init и в интерактивен режим задаваме ключовите параметри за изграждане на документацията. Подробно описание на минималните настройки на проекта тук.
   1. При настройката е важно да укажете изходната директория ..public — GitLab по подразбиране взима съдържанието на папката public в корена на репозитория като източник за Pages. Тъй като проектът ще бъде разположен в вложена в репозитория папка — добавяме в пътя изход на ниво нагоре.
2. Ще изпратим промените в GitLab.
3. В конфигурацията на пайплайна добавяме задача 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. Възел artifacts:

pages:
  # snip
  artifacts:
    paths:
      - public

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

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

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

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

Промеждутъчен извод

Такава проста конфигурация може да се състави буквално за половин час и две чаши кафе, която ще позволява при всяко искане за сливане и изпращане в master да проверяваме, че кодът се събира и тестовете минават, да събираме нов пакет, да обновяваме документацията и да радва очите с красиви значки в 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 pipelines:

Значка със линк към документацията създадох на платформата Shields.io — там всичко е достатъчно просто, можеш да създадеш своя значка и да я получиш с помощта на заявка.

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

Azure DevOps Artifacts също позволява да създаваш значки за пакети с указание на актуалната версия. За целта в източника на сайта Azure DevOps е необходимо да натиснеш на Create badge за избрания пакет и да копираш markdown-разметката:

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

Извеждаме общи фрагменти от конфигурацията

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

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

.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) (rev. / 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 и автоматично определяне на целевата среда, което ще бъде разгледано в следващата статия.

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