🥇 (Скоро) комплетан водич за почетнике за ЦИ/ЦД у ГитЛабу

Или како да добијете прелепе значке за свој пројекат у једној вечери опуштеног кодирања

Вероватно сваки програмер који у неком тренутку има бар један пројекат за кућне љубимце има свраб за лепим беџевима са статусима, покривеношћу кода, верзијама пакета у нугету... И овај свраб ме је навео да напишем овај чланак. У процесу припреме за писање, стекао сам ову лепоту у једном од својих пројеката:

Овај чланак ће покрити основно подешавање континуиране интеграције и испоруке за пројекат библиотеке класа .Нет Цоре у ГитЛаб-у, објављивање документације на ГитЛаб страницама и слање прикупљених пакета у приватни фид у Азуре ДевОпс.

ВС Цоде са екстензијом је коришћен као развојно окружење ГитЛаб Воркфлов (да бисте потврдили датотеку поставки директно из развојног окружења).

Кратки увод

ЦД је када сте само гурнули, а клијент је већ све изгубио?

Шта је ЦИ/ЦД и зашто је потребан? Можете га лако прогуглати. Пронађите комплетну документацију о подешавању цевовода у ГитЛабу такође лако. Овде ћу укратко и, ако је могуће, без недостатака, описати процес система из птичје перспективе:

програмер шаље урезивање у спремиште, креира захтев за стапање преко веб локације, или на неки други начин експлицитно или имплицитно покреће цевовод,
из конфигурације се бирају сви задаци чији услови дозвољавају њихово покретање у датом контексту,
задаци су организовани према својим фазама,
фазе се извршавају редом – тј. паралелно сви задаци ове фазе су завршени,
ако фаза не успе (тј. бар један од задатака фазе не успе) - цевовод се зауставља (готово увек),
ако су све фазе успешно завршене, гасовод се сматра успешним.

Тако имамо:

пипелине је скуп задатака организованих у фазе у којима можете саставити, тестирати, паковати код, распоредити готови склоп на услугу у облаку итд.
фаза (фаза) — јединица организације цевовода, садржи 1+ задатак,
задатак (посао) је јединица рада у цевоводу. Састоји се од скрипте (обавезно), услова покретања, подешавања за објављивање/кеширање артефаката и још много тога.

Сходно томе, задатак при постављању ЦИ/ЦД-а се своди на креирање скупа задатака који имплементирају све неопходне радње за склапање, тестирање и објављивање кода и артефаката.

Пре него што почнемо: зашто?

Зашто ГитЛаб?

Јер када се појавила потреба за креирањем приватних репозиторија за пројекте кућних љубимаца, они су били плаћени на ГитХуб-у, а ја сам био похлепан. Спремишта су постала бесплатна, али за сада ово није довољно добар разлог да пређем на ГитХуб.

Зашто не Азуре ДевОпс Пипелинес?

Пошто је подешавање једноставно - није вам ни потребно знање командне линије. Интеграција са спољним гит провајдерима – у пар кликова, увоз ССХ кључева за слање урезивања у спремиште – такође, цевовод се лако конфигурише чак и без шаблона.

Почетна позиција: шта имате и шта желите

Имамо:

спремиште у ГитЛабу.

Желимо:

аутоматско склапање и тестирање за сваки захтев за спајање,
прављење пакета за сваки захтев за спајање и гурање до мастера, под условом да постоји одређена линија у поруци урезивања,
слање прикупљених пакета у приватни фид у Азуре ДевОпс-у,
састављање документације и објављивање у ГитЛаб Пагес,
значке!11

Описани захтеви се природно уклапају у следећи модел цевовода:

Фаза 1 - монтажа
- Сакупљамо код, објављујемо излазне датотеке као артефакте
Фаза 2 - тестирање
- Примамо артефакте из фазе израде, покрећемо тестове, прикупљамо податке о покривености кода
Фаза 3 - слање
- Задатак 1 - прикупите нугет пакет и пошаљите га у Азуре ДевОпс
- Задатак 2 - састављамо сајт из кмлдоц-а у изворни код и објављујемо га у ГитЛаб Пагес

Хајде да почнемо!

Састављање конфигурације

Припрема рачуна

Направите налог у Мицрософт Азуре
Иди на Азуре ДевОпс
Креирајте нови пројекат
1. Име - било које
2. Видљивост - било која
Када кликнете на дугме Креирај, пројекат ће бити креиран и бићете одведени на његову страницу. На овој страници можете да онемогућите непотребне функције тако што ћете отићи на подешавања пројекта (доња веза на листи са леве стране -> Преглед -> блок Азуре ДевОпс Сервицес)
Идите на Атрифацтс, кликните на Креирај фид
1. Унесите назив извора
2. Изаберите видљивост
3. Опозовите избор у пољу за потврду Укључите пакете из уобичајених јавних изворада се извор не претвори у ђубриште нугет клона
Кликните на Цоннецт то феед, изаберите Висуал Студио, копирајте Соурце из блока за подешавање машине
Идите на подешавања налога, изаберите Лични токен за приступ
Креирајте нови токен за приступ
1. Назив - произвољан
2. Организација – актуелна
3. Рок важења: максимално 1 година
4. Обим – паковање/читање и писање
Копирајте креирани токен - након затварања модалног прозора вредност неће бити доступна
Идите на подешавања спремишта у ГитЛаб-у, изаберите ЦИ/ЦД подешавања
Проширите блок Променљиве и додајте нови
1. Име - било које без размака (биће доступно у командној љусци)
2. Вредност је приступни токен из корака 9
3. Изаберите променљиву маске

Ово завршава прелиминарно подешавање.

Припрема конфигурационог оквира

Подразумевано, датотека која се користи за конфигурисање ЦИ/ЦД-а у ГитЛаб-у је .gitlab-ci.yml из корена спремишта. Можете да конфигуришете прилагођену путању до ове датотеке у подешавањима спремишта, али у овом случају то није неопходно.

Као што се може видети из екстензије, датотека садржи конфигурацију у формату YAML. Документација детаљно описује који кључеви могу бити садржани на највишем нивоу конфигурације и на сваком од угнежђених нивоа.

Прво, додајмо у конфигурациону датотеку везу до доцкер слике у којој ће се задаци извршавати. Да бисмо то урадили налазимо Страница слика .Нет Цоре на Доцкер Хуб-у. У ГитХуб Постоји детаљан водич о томе коју слику одабрати за различите задатке. Слика са .Нет Цоре 3.1 је погодна за нас да направимо, па је слободно додајте као први ред у конфигурацију

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

Сада, када покренете цевовод, наведена слика ће бити преузета из Мицрософтовог спремишта слика, у којој ће се извршавати сви задаци из конфигурације.

Следећи корак је додавање фаза'с. ГитЛаб подразумевано дефинише 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. ВТФ?

Све је логично - подразумевано, тркачи (одговорни за извршавање скрипти задатака и које обезбеђује ГитЛаб) користе 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

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

Подешавање окидача

Због чињенице да нису наведени филтери окидача ни за један од задатака, цевовод ће потпуно извршава се сваки пут када се урезивања шаљу у спремиште. Пошто ово уопште није жељено понашање, конфигурисаћемо филтере окидача за задатке.

Филтери се могу конфигурисати у два формата: само/осим и pravila. Укратко, only/except омогућава вам да конфигуришете филтере помоћу покретача (merge_request, на пример - конфигурише задатак да се извршава сваки пут када се креира захтев за стапање и сваки пут када се урезивања шаљу грани која је извор у захтеву за стапање) и имена грана (укључујући коришћење регуларних израза); rules омогућава вам да прилагодите скуп услова и, опционо, промените услов извршења задатка у зависности од успеха претходних задатака (when у ГитЛаб ЦИ/ЦД).

Подсетимо се скупа захтева – склапање и тестирање само за захтеве за спајање, паковање и слање у Азуре ДевОпс – за захтеве за спајање и гурања ка мастеру, генерисање документације – за пусх до мастера.

Прво, поставимо задатак састављања кода додавањем правила окидача које покреће само захтев за спајање:

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/*

Путања подржавају џокер знакове, што их дефинитивно чини лакшим за постављање.

Ако задатак креира артефакте, онда ће сваки следећи задатак моћи да им приступи – они ће се налазити дуж истих путања у односу на корен спремишта дуж којег су прикупљени од првобитног задатка. Артефакти су такође доступни за преузимање на веб локацији.

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

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

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

dotnet build
dotnet test
dotnet pack

Наравно, постоје неке нијансе због којих ћемо донекле закомпликовати команде.

Желимо издање, а не дебуг, буилд, па додајемо свакој команди -c Release
Приликом тестирања желимо да прикупимо податке о покривености кода, тако да морамо да повежемо анализатор покривености са тест библиотекама:
1. Пакет треба додати свим тест библиотекама coverlet.msbuild: dotnet add package coverlet.msbuild из фасцикле пројекта
2. Додајте у команду за пробно покретање /p:CollectCoverage=true
3. Хајде да додамо кључ у конфигурацију задатка тестирања да бисмо добили резултате покривености (погледајте доле)
Када пакујемо код у нугет пакете, поставићемо излазни директоријум за пакете: -o .

Прикупљање података о покривености кода

Након покретања тестова, Цоверлет приказује статистику покретања на конзоли:

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% |
+---------+--------+--------+--------+

ГитЛаб вам омогућава да наведете регуларни израз за добијање статистике, која се затим може добити у облику значке. Регуларни израз је наведен у подешавањима задатка помоћу кључа coverage; израз мора да садржи групу за снимање, чија ће вредност бити пренета на значку:

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

Овде добијамо статистику из линије са укупном покривеношћу линијама.

Објављујемо пакете и документацију

Обе радње су додељене последњој фази гасовода - пошто су монтажа и тестови прошли, можемо да поделимо наш развој са светом.

Прво, погледајмо објављивање у извору пакета:

Ако пројекат нема конфигурациону датотеку нугет (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 — УРЛ извора из фазе „Припрема налога“, корак 6
3. organization - назив организације у Азуре ДевОпс-у
4. gitlab variable — назив променљиве са токеном за приступ додат у ГитЛаб („Припрема налога“, стр. 11). Наравно, у формату $variableName
5. -StorePasswordInClearText — хак да заобиђе грешку одбијеног приступа (Нисам први који је стао на ове грабље)
6. У случају грешака може бити корисно додати -verbosity detailed
Шаљемо пакет извору: nuget push -source <name> -skipduplicate -apikey <key> *.nupkg
1. Све пакете шаљемо из тренутног директоријума, дакле *.nupkg.
2. name - са корака изнад.
3. key - било која линија. У Азуре ДевОпс-у, у прозору Повежи се са фидом, пример је увек az.
4. -skipduplicate — ако покушате да пошаљете већ постојећи пакет без овог кључа, извор ће вратити грешку 409 Conflict; са кључем, слање ће бити прескочено.

Сада да поставимо креирање документације:

За почетак, у спремишту, у главној грани, иницијализујемо доцфк пројекат. Да бисте то урадили, потребно је да покренете команду из корена docfx init и интерактивно поставити кључне параметре за склапање документације. Детаљан опис минималног подешавања пројекта овде.
1. Приликом подешавања важно је навести излазни директоријум ..public - ГитЛаб подразумевано узима садржај јавне фасцикле у корену спремишта као извор за странице. Јер пројекат ће се налазити у фасцикли која је угнежђена у спремишту - додајте излаз на следећи ниво путањи.
Хајде да пребацимо промене у ГитЛаб.
Додајте задатак у конфигурацију цевовода pages (резервисана реч за задатке објављивања сајта у ГитЛаб страницама):
1. Скрипта:
  1. nuget install docfx.console -version 2.51.0 - инсталирати доцфк; Верзија је обезбеђена да би се осигурало да су путање за инсталацију пакета исправне.
  2. .docfx.console.2.51.0toolsdocfx.exe .docfx_projectdocfx.json — прикупљање документације
2. Чвор артефаката:

pages:
  # snip
  artifacts:
    paths:
      - public

Лирска дигресија о доцфк-у

Раније сам, приликом постављања пројекта, навео извор кода за документацију као датотеку решења. Главни недостатак је што се документација креира и за тест пројекте. Ако ово није неопходно, можете поставити ову вредност на чвор metadata.src:

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

metadata.src.src: "../" — идите један ниво горе у односу на локацију docfx.json, јер Претраживање стабла директоријума не ради у обрасцима.
metadata.src.files: ["**/*.csproj"] — глобални образац, прикупљамо све Ц# пројекте из свих директоријума.
metadata.src.exclude: ["*.tests*/**"] - глобални образац, искључите све из фасцикли са .tests У наслову

Међузбир

Ова једноставна конфигурација се може направити за буквално пола сата и пар шољица кафе, што ће вам омогућити да са сваким захтевом за спајање проверите и пошаљете га мајстору да ли се код гради и да тестови пролазе, склапајући нови пакет, ажурирање документације и угађање оку прелепим беџевима у пројекту РЕАДМЕ.

Финал .гитлаб-ци.имл

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

Говорећи о значкама

Због њих је све почело!

Значке са статусима цевовода и покривеношћу кода су доступне у ГитЛаб-у у подешавањима ЦИ/ЦД у блоку Гтнтрал цевовода:

Направио сам значку са везом до документације на платформи Схиелдс.ио — тамо је све прилично једноставно, можете креирати сопствену значку и добити је помоћу захтева.

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

Азуре ДевОпс артефакти вам такође омогућавају да креирате значке за пакете који указују на најновију верзију. Да бисте то урадили, у извору на веб локацији Азуре ДевОпс, потребно је да кликнете на Креирај значку за изабрани пакет и копирате маркдовн:

Додавање лепоте

Издвајамо уобичајене фрагменте конфигурације

Док сам писао конфигурацију и претраживао документацију, наишао сам на занимљиву ИАМЛ функцију - поновно коришћење фрагмената.

Као што видите из подешавања задатка, сви они захтевају ознаку windows из покретача, а покрећу се приликом слања захтева за спајање мастеру/креирања захтева за спајање (осим за документацију). Хајде да додамо ово фрагменту који ћемо поново користити:

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

И сада можемо да убацимо претходно најављени фрагмент у опис задатка:

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

Називи фрагмената морају да почињу тачком да се не би тумачили као задатак.

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

Приликом креирања пакета, компајлер проверава прекидаче командне линије, а у њиховом одсуству, датотеке пројекта; Након што је пронашао чвор Версион, он узима своју вредност као верзија пакета који се прави. Испоставило се да да бисте направили пакет са новом верзијом, морате или да га ажурирате у датотеци пројекта или да га проследите као аргумент командне линије.

Хајде да додамо још једну жељу – нека најнижа два броја у верзији буду година и датум израде пакета и додајмо прелеасе верзије. Наравно, можете додати ове податке у пројектну датотеку и проверити их пре сваког слања – али то можете да урадите и у току, прикупљајући верзију пакета из контекста и проследујући је кроз аргумент командне линије.

Хајде да се договоримо да ако порука урезивања садржи линију као 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 и стриктно посматрајте састављање пакета ако постоји дата линија у поруци урезивања.

Укупно

Након што смо потрошили око пола сата до сат времена на писање конфигурације, отклањање грешака у локалном поверсхелл-у и, могуће, неколико неуспешних покретања, добили смо једноставну конфигурацију за аутоматизацију рутинских задатака.

Наравно, ГитЛаб ЦИ/ЦД је много обимнији и вишеструки него што би могло изгледати након читања овог водича - то уопште није тачно. Има чак Ауто ДевОпс дадозвољавајући

аутоматски открива, прави, тестира, примењује и надгледа ваше апликације

Сада су планови да се конфигурише цевовод за примену апликација у Азуре, користећи Пулуми и аутоматски детектујући циљно окружење, што ће бити покривено у следећем чланку.

Извор: ввв.хабр.цом