🥇Guide till CI/CD i GitLab för den (nästan) absoluta nybörjaren

Eller hur du får vackra märken för ditt projekt på en kväll med enkel kodning

Förmodligen har varje utvecklare som har minst ett husdjursprojekt vid något tillfälle tjat om vackra märken med status, kodtäckning, paketversioner i nuget ... Och detta kliar fick mig att skriva den här artikeln. Som förberedelse för att skriva den fick jag den här skönheten i ett av mina projekt:

Den här artikeln leder dig genom den grundläggande installationen av kontinuerlig integration och leverans för ett .Net Core-klassbiblioteksprojekt i GitLab, publicering av dokumentation till GitLab-sidor och överföring av byggda paket till ett privat flöde i Azure DevOps.

VS Code användes som utvecklingsmiljö med tillägget GitLab arbetsflöde (för att validera inställningsfilen direkt från utvecklingsmiljön).

Kort introduktion

CD - är det när du bara tryckte, och allt har redan fallit på klienten?

Vad är CI/CD och varför du behöver det – du kan enkelt googla det. Hitta komplett dokumentation om att konfigurera pipelines i GitLab också lätt. Här kommer jag kort och om möjligt utan brister att beskriva systemets process ur fågelperspektiv:

utvecklaren skickar en commit till arkivet, skapar en sammanslagningsförfrågan via webbplatsen, eller på annat sätt, explicit eller implicit startar pipelinen,
alla uppgifter väljs från konfigurationen, vars villkor tillåter dem att startas i det givna sammanhanget,
uppgifterna är organiserade efter deras stadier,
etapper utförs i tur och ordning - d.v.s. parallell alla uppgifter i detta skede är slutförda,
om steget misslyckas (d.v.s. minst en av stegets uppgifter misslyckas), stannar pipelinen (nästan alltid),
om alla steg genomförs framgångsrikt anses pipelinen vara framgångsrik.

Så vi har:

pipeline - en uppsättning uppgifter organiserade i steg där du kan bygga, testa, paketera kod, distribuera en färdig build till en molntjänst, etc.,
skede (skede) — pipeline organisationsenhet, innehåller 1+ uppgift,
uppgift (jobb) är en arbetsenhet i pipelinen. Den består av ett skript (obligatoriskt), startvillkor, inställningar för publicering/cachelagring av artefakter och mycket mer.

Följaktligen handlar uppgiften när du ställer in CI / CD om att skapa en uppsättning uppgifter som implementerar alla nödvändiga åtgärder för att bygga, testa och publicera kod och artefakter.

Innan du börjar: varför?

Varför Gitlab?

För när det blev nödvändigt att skapa privata arkiv för husdjursprojekt fick de betalt på GitHub, och jag var girig. Lagren har blivit gratis, men än så länge är detta inte tillräckligt skäl för mig att flytta till GitHub.

Varför inte Azure DevOps Pipelines?

För där är inställningen elementär - kunskap om kommandoraden krävs inte ens. Integration med externa git-leverantörer - med ett par klick, import av SSH-nycklar för att skicka commits till förvaret - också, pipelinen konfigureras enkelt även om den inte är från en mall.

Utgångsposition: vad du har och vad du vill ha

Vi har:

arkiv i GitLab.

Vi vill:

automatisk montering och testning för varje sammanslagningsförfrågan,
bygga paket för varje sammanslagningsbegäran och trycka till mastern, förutsatt att det finns en viss rad i commit-meddelandet,
skicka byggda paket till ett privat flöde i Azure DevOps,
sammanställning av dokumentation och publicering i GitLab-sidor,
märken!11

De beskrivna kraven faller organiskt på följande pipelinemodell:

Steg 1 - montering
- Vi samlar in koden, publicerar utdatafilerna som artefakter
Steg 2 - testning
- Vi får artefakter från byggstadiet, kör tester, samlar in kodtäckningsdata
Steg 3 - Skicka in
- Uppgift 1 – bygg nuget-paketet och skicka det till Azure DevOps
- Uppgift 2 - vi samlar in webbplatsen från xmldoc i källkoden och publicerar den i GitLab Pages

Låt oss börja!

Samlar in konfigurationen

Förbereder konton

Skapa ett konto i Microsoft Azure
Gå till Azure DevOps
Vi skapar ett nytt projekt
1. Namn - vilket som helst
2. Synlighet - vilken som helst
När du klickar på knappen Skapa skapas projektet och du omdirigeras till dess sida. På den här sidan kan du inaktivera onödiga funktioner genom att gå till projektinställningarna (nedre länken i listan till vänster -> Översikt -> Azure DevOps Services-blocket)
Gå till Atrifacts, klicka på Skapa flöde
1. Ange namnet på källan
2. Välj synlighet
3. Avmarkera Inkludera paket från vanliga offentliga källor, så att källan inte förvandlas till en dump nuget-klon
Klicka på Anslut till flöde, välj Visual Studio, kopiera källa från maskininställningsblocket
Gå till kontoinställningar, välj Personal Access Token
Skapa en ny åtkomsttoken
1. Namn - godtyckligt
2. Organisation - Aktuell
3. Gäller max 1 år
4. Omfattning - Förpackning/Läs & Skriv
Kopiera den skapade token - efter att modalfönstret stängts kommer värdet inte att vara tillgängligt
Gå till förvarsinställningarna i GitLab, välj CI / CD-inställningarna
Expandera variabelblocket, lägg till ett nytt
1. Namn - vilket som helst utan mellanslag (kommer att vara tillgängligt i kommandoskalet)
2. Värde - åtkomsttoken från punkt 9
3. Välj Mask variabel

Detta slutför förkonfigurationen.

Förbereder konfigurationsramverket

Som standard använder CI/CD-konfiguration i GitLab filen .gitlab-ci.yml från roten av förvaret. Du kan ställa in en godtycklig sökväg till den här filen i förvarsinställningarna, men i det här fallet är det inte nödvändigt.

Som du kan se av tillägget innehåller filen en konfiguration i formatet YAML. Dokumentationen beskriver vilka nycklar som kan finnas på den översta nivån av konfigurationen och på var och en av de kapslade nivåerna.

Låt oss först lägga till en länk till docker-bilden i konfigurationsfilen, där uppgifterna kommer att utföras. För detta finner vi .Net Core-bildsida på Docker Hub. I GitHub det finns en detaljerad guide om vilken bild man ska välja för olika uppgifter. En bild med .Net Core 3.1 är lämplig för oss att bygga, så lägg gärna till den första raden i konfigurationen

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

Nu, när pipelinen startas från Microsofts bildarkiv, kommer den angivna bilden att laddas ner, där alla uppgifter från konfigurationen kommer att utföras.

Nästa steg är att lägga till skedes. Som standard definierar GitLab 5 steg:

.pre - framförs upp till alla stadier,
.post - framförs efter alla stadier,
build - först efter .pre skede,
test - andra fasen,
deploy - det tredje steget.

Inget hindrar dig dock från att deklarera dem uttryckligen. Ordningen i vilken stegen listas påverkar i vilken ordning de utförs. För fullständighetens skull, låt oss lägga till i konfigurationen:

stages:
  - build
  - test
  - deploy

För felsökning är det vettigt att få information om miljön där uppgifterna utförs. Låt oss lägga till en global uppsättning kommandon som kommer att köras före varje uppgift med before_script:

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

Det återstår att lägga till minst en uppgift så att pipelinen startar när commits skickas. För nu, låt oss lägga till en tom uppgift för att demonstrera:

dummy job:
  script:
    - echo ok

Vi börjar validera, vi får ett meddelande om att allt är bra, vi förbinder oss, vi trycker på, vi tittar på resultaten på webbplatsen ... Och vi får ett skriptfel - bash: .PSVersion: command not found. wtf?

Allt är logiskt - som standard använder löpare (ansvariga för att köra uppgiftsskript och tillhandahålls av GitLab) bash för att utföra kommandon. Du kan åtgärda detta genom att uttryckligen ange i uppgiftsbeskrivningen vilka taggar den körande pipeline-runnern ska ha:

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

Bra! Pipeledningen är nu igång.

En uppmärksam läsare, efter att ha upprepat de angivna stegen, kommer att märka att uppgiften slutfördes i scenen test, även om vi inte angav scenen. Som du kanske gissar test är standardsteget.

Låt oss fortsätta skapa konfigurationsskelettet genom att lägga till alla uppgifter som beskrivs ovan:

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

Vi fick en inte särskilt funktionell, men ändå korrekt pipeline.

Ställa in triggers

På grund av att inga triggerfilter är specificerade för någon av uppgifterna kommer pipelinen att göra det fullt exekveras varje gång en commit skickas till förvaret. Eftersom detta inte är det önskade beteendet i allmänhet kommer vi att sätta upp triggerfilter för uppgifter.

Filter kan konfigureras i två format: endast/utom и regler. I korthet, only/except låter dig konfigurera filter efter utlösare (merge_request, till exempel - ställer in uppgiften så att den exekveras varje gång en pull-begäran skapas och varje gång commits skickas till grenen som är källan i sammanslagningsbegäran) och grennamn (inklusive användning av reguljära uttryck); rules låter dig anpassa en uppsättning villkor och, valfritt, ändra villkoret för uppgiftskörning beroende på framgången med tidigare uppgifter (when i GitLab CI/CD).

Återkalla kravuppsättningen - montering och testning endast för sammanslagningsbegäran, paketering och sändning till Azure DevOps - för sammanslagningsbegäran och pushar till mastern, dokumentationsgenerering - för pushar till mastern.

Låt oss först ställa in kodbyggeuppgiften genom att lägga till en regel som endast aktiveras vid sammanfogningsbegäran:

build job:
  # snip
  only:
    - merge_request

Låt oss nu ställa in paketeringsuppgiften så att den aktiveras på en sammanslagningsförfrågan och lägger till commits till mastern:

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

Som du kan se är allt enkelt och okomplicerat.

Du kan också ställa in uppgiften att aktiveras endast om en sammanslagningsbegäran skapas med ett specifikt mål eller källgren:

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

Under förhållanden kan du använda variabler listade här; regler rules oförenlig med reglerna only/except.

Konfigurera Artifact Saving

Under en uppgift build job vi kommer att bygga artefakter som kan återanvändas i efterföljande uppgifter. För att göra detta måste du lägga till sökvägarna till uppgiftskonfigurationen, filerna som du måste spara och återanvända i följande uppgifter, till nyckeln artifacts:

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

Sökvägar stöder jokertecken, vilket definitivt gör dem lättare att ställa in.

Om en uppgift skapar artefakter, kommer varje efterföljande uppgift att kunna komma åt dem - de kommer att placeras längs samma vägar i förhållande till förvarsroten som samlades in från den ursprungliga uppgiften. Artefakter finns också tillgängliga för nedladdning på sajten.

Nu när vi har ett konfigurationsramverk klart (och testat) kan vi fortsätta med att faktiskt skriva skript för uppgifter.

Vi skriver manus

Kanske, en gång i tiden, i en galax långt, långt borta, var det jobbigt att bygga projekt (inklusive de på .net) från kommandoraden. Nu kan du bygga, testa och publicera projektet i 3 team:

dotnet build
dotnet test
dotnet pack

Naturligtvis finns det några nyanser på grund av vilka vi kommer att komplicera kommandona något.

Vi vill ha en release-build, inte en debug-build, så vi lägger till varje kommando -c Release
När vi testar vill vi samla in kodtäckningsdata, så vi måste inkludera en täckningsanalysator i testbiblioteken:
1. Lägg till paketet i alla testbibliotek coverlet.msbuild: dotnet add package coverlet.msbuild från projektmappen
2. Lägg till i testkörningskommandot /p:CollectCoverage=true
3. Lägg till en nyckel till testuppgiftskonfigurationen för att få täckningsresultat (se nedan)
När du packar koden i nuget-paket, ställ in utdatakatalogen för paketen: -o .

Samlar in kodtäckningsdata

Efter att ha kört testerna skriver Coverlet ut körstatistik till konsolen:

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 låter dig specificera ett reguljärt uttryck för att få statistik, som sedan kan erhållas i form av ett märke. Det reguljära uttrycket anges i uppgiftsinställningarna med nyckeln coverage; uttrycket måste innehålla en fångstgrupp, vars värde kommer att skickas till märket:

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

Här får vi statistik från en linje med total linjetäckning.

Publicera paket och dokumentation

Båda åtgärderna är schemalagda för det sista steget av pipelinen - eftersom monteringen och testerna har passerat kan vi dela vår utveckling med världen.

Överväg först att publicera till paketkällan:

Om projektet inte har en nuget-konfigurationsfil (nuget.config), skapa en ny: dotnet new nugetconfig

För vad: bilden kanske inte har skrivåtkomst till globala (användare och maskin) konfigurationer. För att inte fånga fel skapar vi helt enkelt en ny lokal konfiguration och arbetar med den.
Låt oss lägga till en ny paketkälla till den lokala konfigurationen: nuget sources add -name <name> -source <url> -username <organization> -password <gitlab variable> -configfile nuget.config -StorePasswordInClearText
1. name - lokalt källnamn, inte kritiskt
2. url - URL till källan från steget "Förbereda konton", s. 6
3. organization - organisationsnamn i Azure DevOps
4. gitlab variable - Namnet på variabeln med åtkomsttoken lagt till GitLab ("Förbereda konton", s. 11). Naturligtvis i formatet $variableName
5. -StorePasswordInClearText - ett hack för att kringgå felet nekad åtkomst (Jag är inte den första som trampar på den här raken)
6. Vid fel kan det vara bra att lägga till -verbosity detailed
Skicka paketet till källan: nuget push -source <name> -skipduplicate -apikey <key> *.nupkg
1. Vi skickar alla paket från den aktuella katalogen, så *.nupkg.
2. name - från steget ovan.
3. key - vilken rad som helst. I Azure DevOps, i fönstret Anslut till flöde, är exemplet alltid raden az.
4. -skipduplicate - när du försöker skicka ett redan befintligt paket utan denna nyckel kommer källan att returnera ett fel 409 Conflict; med nyckeln hoppas sändningen över.

Låt oss nu ställa in skapandet av dokumentation:

Först, i förvaret, i mastergrenen, initierar vi docfx-projektet. För att göra detta, kör kommandot från roten docfx init och interaktivt ställa in nyckelparametrarna för byggnadsdokumentation. Detaljerad beskrivning av minsta projektuppsättning här.
1. Vid konfigurering är det viktigt att ange utdatakatalogen ..public - GitLab tar som standard innehållet i den offentliga mappen i roten av förvaret som en källa för Pages. Därför att projektet kommer att ligga i en mapp kapslad i arkivet - lägg till en utdata till nivån upp i sökvägen.
Låt oss driva ändringarna till GitLab.
Lägg till en uppgift till pipelinekonfigurationen pages (reserverat ord för webbplatspubliceringsuppgifter i GitLab-sidor):
1. Manus:
  1. nuget install docfx.console -version 2.51.0 - installera docfx; versionen anges för att säkerställa att paketets installationssökvägar är korrekta.
  2. .docfx.console.2.51.0toolsdocfx.exe .docfx_projectdocfx.json - samla in dokumentation
2. Nodartefakter:

pages:
  # snip
  artifacts:
    paths:
      - public

Lyrisk utvikning om docfx

Tidigare, när jag satte upp ett projekt, angav jag kodkällan för dokumentationen som en lösningsfil. Den största nackdelen är att dokumentation skapas även för testprojekt. Om detta inte är nödvändigt kan du ställa in ett sådant värde till noden metadata.src:

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

metadata.src.src: "../" – vi går en nivå upp i förhållande till läget docfx.json, därför att i mönster fungerar det inte att söka i katalogträdet.
metadata.src.files: ["**/*.csproj"] - ett globalt mönster, vi samlar alla C #-projekt från alla kataloger.
metadata.src.exclude: ["*.tests*/**"] - globalt mönster, uteslut allt från mappar med .tests I titeln

Delsumma

En sådan enkel konfiguration kan skapas på bara en halvtimme och ett par koppar kaffe, vilket gör att du kan kontrollera att koden är byggd och att testerna passerar, bygga ett nytt paket, uppdatera dokumentationen och glädja ögat med vackra märken i README för projektet med varje sammanslagningsförfrågan och sändning till mastern.

Slutlig .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

På tal om märken

På grund av dem var ju allt igång!

Märken med pipelinestatus och kodtäckning är tillgängliga i GitLab i CI/CD-inställningarna i Gtntral pipelines-blocket:

Jag skapade ett märke med en länk till dokumentationen på plattformen Shields.io - allt är ganska enkelt där, du kan skapa ditt eget märke och få det med en förfrågan.

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

Azure DevOps Artifacts låter dig också skapa märken för paket med den senaste versionen. För att göra detta måste du i källan på Azure DevOps-webbplatsen klicka på Skapa märke för det valda paketet och kopiera markeringen:

Lägger till skönhet

Markera vanliga konfigurationsfragment

När jag skrev konfigurationen och sökte igenom dokumentationen stötte jag på en intressant egenskap hos YAML - att återanvända fragment.

Som du kan se från uppgiftsinställningarna kräver de alla taggen windows hos löparen, och utlöses när en sammanslagningsförfrågan skickas till mastern/skapas (förutom dokumentation). Låt oss lägga till detta till fragmentet som vi kommer att återanvända:

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

Och nu kan vi infoga fragmentet som deklarerades tidigare i uppgiftsbeskrivningen:

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

Fragmentnamn måste börja med en punkt, för att inte tolkas som en uppgift.

Paketversionering

När du skapar ett paket kontrollerar kompilatorn kommandoradsväxlarna och i frånvaro projektfilerna; när den hittar en versionsnod tar den dess värde som versionen av paketet som byggs. Det visar sig att för att bygga ett paket med en ny version måste du antingen uppdatera det i projektfilen eller skicka det som ett kommandoradsargument.

Låt oss lägga till ytterligare en önskelista - låt de två mindre siffrorna i versionen vara år och byggdatum för paketet, och lägg till förhandsversioner. Naturligtvis kan du lägga till denna data i projektfilen och kontrollera före varje inlämning - men du kan också göra det i pipelinen, samla in paketversionen från sammanhanget och skicka den genom kommandoradsargumentet.

Låt oss komma överens om att om commit-meddelandet innehåller en rad som release (v./ver./version) <version number> (rev./revision <revision>)?, så tar vi versionen av paketet från den här raden, kompletterar den med det aktuella datumet och skickar det som ett argument till kommandot dotnet pack. I avsaknad av en rad kommer vi helt enkelt inte att hämta paketet.

Följande skript löser detta problem:

# регулярное выражение для поиска строки с версией
$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

Lägga till ett skript till en uppgift pack and deploy job och observera sammansättningen av paket strikt i närvaro av en given sträng i commit-meddelandet.

Totalt

Efter att ha spenderat ungefär en halvtimme eller en timme på att skriva konfigurationen, felsöka i det lokala powershell och möjligen ett par misslyckade lanseringar, fick vi en enkel konfiguration för att automatisera rutinuppgifter.

Givetvis är GitLab CI / CD mycket mer omfattande och mångfacetterad än det kan verka efter att ha läst den här guiden - det stämmer inte alls. Där till och med Auto DevOps ärtillåter

automatiskt upptäcka, bygga, testa, distribuera och övervaka dina applikationer

Nu är planerna att konfigurera en pipeline för att distribuera applikationer till Azure, använda Pulumi och automatiskt bestämma målmiljön, vilket kommer att behandlas i nästa artikel.

Källa: will.com

En guide till CI/CD i GitLab för den (nästan) absoluta nybörjaren