Водич за CI/CD во GitLab за (речиси) апсолутен почетник

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

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

Оваа статија ќе ве води низ основното поставување на континуирана интеграција и испорака за проект за библиотека од класа .Net Core во GitLab, објавување документација на страниците на GitLab и туркање на вградените пакети до приватен извор во Azure DevOps.

VS Code беше користен како развојна околина со наставката Работен тек на GitLab (за потврдување на датотеката со поставки директно од развојната околина).

Краток вовед

ЦД - дали е кога само сте турнале, а веќе се паднало на клиентот?

Што е CI / CD и зошто ви е потребно - можете лесно да го гуглате. Најдете целосна документација за конфигурирање на цевководи во GitLab исто така лесно. Овде накратко и, ако е можно, без недостатоци ќе го опишам процесот на системот од птичја перспектива:

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

Така, имаме:

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

Соодветно на тоа, задачата при поставување на CI / CD се сведува на создавање збир на задачи што ги спроведуваат сите потребни дејства за градење, тестирање и објавување код и артефакти.

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

• Зошто Gitlab?

Затоа што кога стана неопходно да се создадат приватни складишта за проекти за домашни миленици, тие беа платени на GitHub, а јас бев алчен. Складиштата станаа бесплатни, но засега ова не е доволна причина да се преселам во GitHub.

• Зошто не Azure DevOps Pipelines?

Бидејќи таму поставката е елементарна - дури и не е потребно познавање на командната линија. Интеграција со надворешни провајдери на git - со неколку кликања, увоз на SSH клучеви за испраќање на обврски до складиштето - исто така, нафтоводот лесно се конфигурира дури и не од шаблон.

Почетна позиција: што имате и што сакате

Ние имаме:

• складиште во GitLab.

Ние сакаме:

• автоматско склопување и тестирање за секое барање за спојување,
• градење пакети за секое барање за спојување и притискање до главниот, под услов да има одредена линија во пораката за commit,
• испраќање вградени пакети до приватен извор во Azure DevOps,
• склопување на документација и објавување во GitLab Pages,
• беџови!11

Опишаните барања органски паѓаат на следниов модел на цевковод:

• Фаза 1 - склопување
  • Го собираме кодот, ги објавуваме излезните датотеки како артефакти
• Фаза 2 - тестирање
  • Добиваме артефакти од фазата на изградба, извршуваме тестови, собираме податоци за покривање на кодот
• Фаза 3 - Поднеси
  • Задача 1 - изградете го пакетот nuget и испратете го до Azure DevOps
  • Задача 2 - ја собираме страницата од xmldoc во изворниот код и ја објавуваме во GitLab Pages

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

Собирање на конфигурацијата

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

1. Креирајте сметка во Мајкрософт Сино

2. Оди до Azure DevOps

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

   1. Име - кое било
   2. Видливост - која било
      

4. Кога ќе кликнете на копчето Креирај, проектот ќе се креира и ќе бидете пренасочени на неговата страница. На оваа страница, можете да ги оневозможите непотребните функции со одење до поставките на проектот (долната врска во списокот лево -> Преглед -> Блок на услуги на Azure DevOps)
   

5. Одете во Atrifacts, кликнете Креирај извор

   1. Внесете го името на изворот
   2. Изберете видливост
   3. Отштиклирајте Вклучете пакети од заеднички јавни извори, за да не се претвори изворот во клон на депонија
      

6. Кликнете Поврзи се за довод, изберете Visual Studio, копирајте Source од блокот Machine Setup
   

7. Одете до поставките на сметката, изберете токен за личен пристап
   

8. Создадете нов токен за пристап

   1. Име - произволно
   2. Организација - Тековна
   3. Важи најмногу 1 година
   4. Опсег - Пакување/Читање и пишување
      

9. Копирајте го креираниот токен - откако ќе се затвори модалниот прозорец, вредноста ќе биде недостапна

10. Одете до поставките на складиштето во GitLab, изберете ги поставките за CI / CD
    

11. Проширете го блокот Променливи, додадете нов

    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?

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

Секако, има некои нијанси поради кои малку ќе ги комплицираме командите.

1. Сакаме изработка на издание, а не за отстранување грешки, па додаваме на секоја команда -c Release
2. Кога тестираме, сакаме да собираме податоци за покриеност на кодот, па затоа треба да вклучиме анализатор на покриеност во библиотеките за тестирање:
   1. Додадете го пакетот во сите тест библиотеки coverlet.msbuild: dotnet add package coverlet.msbuild од проектната папка
   2. Додај во командата за тестирање /p:CollectCoverage=true
   3. Додајте клуч во конфигурацијата на тест-задачата за да добиете резултати од покриеност (видете подолу)
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+%)/

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

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

Двете акции се закажани за последната фаза од гасоводот - бидејќи склопувањето и тестовите поминаа, можеме да ги споделиме нашите случувања со светот.

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

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

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

2. Ајде да додадеме нов извор на пакет во локалната конфигурација: 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
3. Испраќање на пакетот до изворот: nuget push -source <name> -skipduplicate -apikey <key> *.nupkg
   1. Ги испраќаме сите пакети од тековниот директориум, така *.nupkg.
   2. name - од чекорот погоре.
   3. key - која било линија. Во Azure DevOps, во прозорецот Connect to feed, примерот е секогаш линијата az.
   4. -skipduplicate - кога се обидувате да испратите веќе постоечки пакет без овој клуч, изворот ќе врати грешка 409 Conflict; со клучот, испраќањето ќе се прескокне.

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

1. Прво, во складиштето, во главната гранка, го иницијализираме проектот docfx. За да го направите ова, извршете ја командата од коренот docfx init и интерактивно поставете ги клучните параметри за градежна документација. Детален опис на минималното поставување на проектот тука.
   1. При конфигурирање, важно е да го наведете излезниот директориум ..public - GitLab стандардно ја зема содржината на јавната папка во коренот на складиштето како извор за Страници. Бидејќи проектот ќе се наоѓа во папка вгнездена во складиштето - додајте излез на нивото нагоре во патеката.
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. Артефакти на јазол:

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 Во насловот

Субтотал

Таква едноставна конфигурација може да се создаде за само половина час и неколку шолји кафе, што ќе ви овозможи да проверите дали кодот е вграден и тестовите да поминат, да изградите нов пакет, да ја ажурирате документацијата и да го задоволите окото со убави значки во 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 Artifacts исто така ви овозможува да креирате значки за пакети со најновата верзија. За да го направите ова, во изворот на страницата Azure DevOps, треба да кликнете на Креирај значка за избраниот пакет и да ја копирате ознаката за означување:

Додавање убавина

Истакнување на вообичаени конфигурациски фрагменти

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

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

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

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

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

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

Верзија на пакети

Кога креирате пакет, компајлерот ги проверува прекинувачите на командната линија, а во нивно отсуство, проектните датотеки; кога ќе најде јазол на верзијата, ја зема неговата вредност како верзијата на пакетот што се гради. Излегува дека за да изградите пакет со нова верзија, треба или да го ажурирате во проектната датотека или да го пренесете како аргумент на командната линија.

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

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

Во вкупен

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

Се разбира, GitLab CI / CD е многу пообемно и повеќеслојно отколку што може да изгледа откако ќе го прочитате овој водич - тоа воопшто не е точно. Дури и таму Автоматски DevOps едозволувајќи

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

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

Извор: www.habr.com