Repositoryk létrehozása és beállítása

1. Repositoryk létrehozása

A gbsolutions csoporton belül hozzunk létre egy új subgroup-ot, ami az ügyfél nevére utaljon és azon belül hozzuk létre a projekthez tartozó subgroupot.

Group létrehozás a gbsolutions groupba

Jelenleg csak az alábbi embereknek van jogosultsága új groupot létrehozni a gbsolutions-ön belül:

név	email cím
Kazsik Ádám	adam.kazsik@intuitech.studio
Katona Áron	aron.katona@intuitech.studio
Surányi Ákos	akos.suranyi@intuitech.studio
Lendvai Richárd	richard.lendvai@intuitech.studio
Sevcsik-Zajácz András	andras.sevcsik-zajacz@intuitech.studio

Közülük kérjünk meg valakit az ügyfél subgroup létrehozására, és kérjünk rá „Owner“ jogosultságot. Azon belül így már létre tudjuk majd hozni a projekt subgroupot.

Több subgroup egy ügyfélhez

Ha adott ügyfélnek több izolált projektet is szállítunk, akkor értelemszerűn egy ügyfél subgroupon belül hozzuk létre a projekt subgroupot.

Példa

Ha az ügyfél neve „Példa Cég Kft.“ és a projekt neve „Legjobb Project“ akkor az alábbi módon hozzuk létre GitLab-on a groupkat:

gbsolutions/pelda-ceg/legjobb-project

Így ha később ennek a cégnek egy új projektet is fejlesztünk: „Legeslegjobb Project“ akkor ahhoz az alábbi módon tudjuk definiálni a groupot:

gbsolutions/pelda-ceg/legeslegjobb-project

A projekt subgroupba hozzuk át a Semi Product éppen aktuális állapotát.

Ehhez használjuk az Import Repo by GitLab export opciót ami a repository konfigurációk jelentős részét is importálja.

Az import lépéseket mindegyik Semi Product projektre hajtsuk végre:

• api
• backend
• frontend
• documentation
• bot

1.1 Repositoryk importálása

Fontos

A SEMI repository-kat mindenképpen Google Chrome böngészőt használva exportáljuk és importáljuk, az esetleges fájlkiterjesztéssel kapcsolatos hibák elkerülése érdekében.

1.1.1 Export repository

SEMI repositoryk exportálása

Fontos, hogy a SEMI repositoryk exportjához legalább „Maintainer“ jogosultság szükséges a SEMI product subgroupban. Amennyiben nem rendelkezünk a megfelelő jogosultsággal, az itt található SEMI csapattagok valamelyikétől kérjünk jogosultságot.

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> General menüpontot.
2. Nyissuk ki az Advanced szekciót.
3. Az Export project bekezdésben kattintsunk az Export project gombra.
4. Ezt követően pár percen belül a GitLab-ra regisztrált email címünkre kapunk egy üzenet az importhoz szükséges tar.gz fájl letöltő linkjével.
5. Mentsük el ezt a fájlt a gépünkre.

Figyelem

A backend exportálása kb. 8 percig tart, és akár 10-15 percig is eltarthat mire megkérkezik az exportot tartalmazó e-mail.
Miután elkészült az export a felületen is megjelenik egy letöltő link.

1.1.2 Import repository

1. GitLabon lépjünk be a projekt subgroupba majd kattintsunk a New project gombra.
2. Válasszuk az Import project opciót.

3. Az Import project from szekcóban válasszuk ki a GitLab export opciót.

   

4. A Project name mezőbe adjuk meg a projekt nevét. Nem javasoljuk a repository-k átnevezését. A későbbi problémák és félreértések elkerülése érdekében a backend projektet, backend néven, a frontend-et, frontend néven importáljuk, és hasonlóan járjunk el a többi projektnél is.

5. A GitLab project export szekcióban válasszuk ki az importálni kívánt tar.gz export fájlt.

   

6. Kattintsunk az Import project gombra az import befejezéséhez.

SEMI-ből örökölt branchek, issue-k, merge requestek, tag-ek

Az importálás következménye, hogy megkapjuk a teljes SEMI Git History-t is a repositoryhoz, beleértve a nyitott brancheket, merge requesteket, esetleges issue-kat és a SEMI-ben létrehozott tageket.

Épp ezért nézzük át az importált repository-kat, és a projekt elején törüljük ki a számunkra nem szükséges brancheket, tageket, mr-eket és issuekat.

Ez a törlés csak a projekt repository-jára érvényes, így nyugodtan töröljünk ki mindent, csak a develop és a main branch megtartása szükséges.

Fontos

Az importálás a backend esetén legalább 60 percig tart.

2. Subgroup konfigurálása

Az alábbi pontokban subgroup alatt mindig az adott projekt subgroup-ját értjük, azaz amennyiben a gbsolutions/pelda-ceg/ ügyfél subgroupban szerepel a mi projektünk subgroupja: gbsolutions/pelda-ceg/pelda-projekt akkor az alábbi beállításokat a pelda-projekt subgroupra kell végrehajtani.

Fontos, hogy a projekt subgroup nem összekeverendő a GitLab projektekkel (pl.: backend, frontend, api stb.)

2.1 Deploy token létrehozása

Hozzunk létre egy deploy tokent. Ezt fogja a VM használni telepítéskor, hogy leszedje a docker imageket a registryből.

1. Az aktuális subgroupba navigálva a baloldali menüsorból válasszuk ki a Settings -> Repository menüpontot.
2. Nyissuk ki a Deploy tokens szekciót.
3. A Name mezőbe adjuk meg a deploy token nevét.

4. A Scopes szekcióban pipáljuk be az alábbiakat:

   • read_repository
   • read_registry
   • write_registry
   • read_package_registry
   • write_package_registry

5. A Create deploy token gombra kattintva hozzuk létre a tokent.

Deploy Token Password

Figyeljünk arra, hogy a deploy token jelszavát csak a létrehozáskor tudjuk megtekinteni és elmenteni.

Amennyiben ezen a ponton elfelejtjük megtenni, később nem lesz lehetőség visszakeresni, hanem új deploy tokent kell készítenünk.

2.2 Group access token létrehozása

Group Access Token vs. Project Access Token

Fontos, hogy ebben a lépésben a teljes subgrouphoz hozzuk létre az access tokent (Pl.: semi-product -> Group Access token), és ne egy specifikus projekthez (Pl.: backend, frontend -> Project Access Token)

Azaz fontos, hogy az alábbi lépések eredménye egy Group Access Token legyen!

Hozzunk létre egy Group Access Tokent a subgrouphoz. Ezt fogja használni az OBR release CI job.

1. Az aktuális subgroupba navigálva (pl.: semi-product) a baloldali menüsorból válasszuk ki a Settings -> Access Tokens menüpontot.
2. Kattintsunk az Add new token gombra.
3. A Token name mezőben adjuk meg a token nevét.
4. A Select a role legördülő mezőben válasszuk ki a Maintainer role-t.

5. A Select scopes szekcióban pipáljuk be az alábbiakat:

   • api
   • read_api
   • read_repository
   • write_repository
   • read_registry
   • write_registry

6. Végül kattintsunk a Create group access token gombra kattintva hozzuk létre a tokent.

Access Token Password

Figyeljünk arra, hogy az access token jelszavát csak a létrehozáskor tudjuk megtekinteni és elmenteni.

Amennyiben ezen a ponton elfelejtjük megtenni, később nem lesz lehetőség visszakeresni, hanem új access tokent kell készítenünk.

2.3 CI változók definiálása

1. Az aktuális subgroupba navigálva a baloldali menüsorból válasszuk ki a Settings -> CI/CD menüpontot.
2. Nyissuk ki a Variables szekciót.
3. Az Add variable gombbal adjuk hozzá az alábbi változókat:

Key	Value	Protect variable	Mask variable	Expand variable reference
DOCKER_AUTH_CONFIG	Érték
DOCKER_REGISTRY_URL	Értéke a backend projekt GitLab container registry-jének elérési útvonala. Pl.: registry.gitlab.com/gbsolutions/semi-product/backend. A registry url az itt leírt lépéseket követve a GitLab felületén is megtalálható. Fontos, hogy a container registry url nem tartalmaz nagybetűket, még akkor sem, ha subgroup-ok nevében használtunk nagybetűket!
DOCKER_REGISTRY_USERNAME	Értéke legyen a Deploy token létrehozása szekcióban létrehozott deploy token username értéke.
DOCKER_REGISTRY_PASSWORD	A Deploy token létrehozása szekcióban létrehozott deploy token jelszava.
GITLAB_RELEASE_TOKEN	A Group Access Token létrehozása szekcióban létrehozott token-hez tartozó password értékét kell itt megadni.
GITLAB_RELEASE_USERNAME	Tetszőleges név a Release job számára. Ez a név fog megjelenni a Release job-hoz tartozó commit-oknál, ezért célszerű az alábbi módon megadni: ${projekt-név} - Release Job. Pl.: Semi Product - Release Job.
GITLAB_RELEASE_EMAIL	A Release job-hoz tartozó commit-oknál megjelenő email cím. Itt célszerű a projekt email csoportjának címét megadni.

Változók értékei:

• DOCKER_AUTH_CONFIG: A SEMI által publikált docker image-ek CI jobokból való eléréséhez szükséges. Értéke legyen:

  {
      "auths": {
          "registry.gitlab.com/gbsolutions/semi-product/backend:5000": {
              "auth": "cmVnaXN0cnktcmVhZC10b2tlbi1mb3Itc2VtaS1wcm9qZWN0czpRY3hxa0dWV3RpeEF1anpNYVRUcA=="
          }
      }
  }
  

• DOCKER_REGISTRY_URL: Értékét megnézhetjük az alábbi lépéseket követve:

  • A frissen importált backend projekt-be navigálva, baloldali menüsávból kiválasztjuk Deploy majd Container registry menüpontot.

  • A megnyíló Container registry képernyőn megjelennek a parancsok, amikkel image-eket pusholhatunk a registry-be. Innen kimásolhatjuk a registry url-t:

    

2.4 Package Registry konfiguráció

Kapcsoljuk ki, hogy ne lehessen duplikáltan (ugyanazon a néven) package-eket feltölteni a GitLab package registry-be.

1. Az aktuális subgroupba navigálva a baloldali menüsorból válasszuk ki a Settings -> Packages and registries menüpontot.

2. A Duplicate packages szekcióban a Package format-ok közül keressük ki a Generic-et, és az Allow duplicates kapcsolót állítsuk kikapcsolt állapotra.

   

3. Repositoryk konfigurálása

Első lépésként minden projekten hozzuk létre a main és develop brancheket. (Amennyiben még nem léteznek.)

Az alábbi konfigurációs lépéseket szintén mindegyik projektre hajtsuk végre:

• api
• backend
• frontend
• documentation

3.1 A default branch beállítása

Default branch beállítása

Az itt található konfigurációt, amennyiben a fent leírt módon importáljuk a projektet, akkor nem kell végrehajtanunk, de érdemes ellenőriznünk, hogy a leírtaknak megfelelő beállításokat látjuk-e a projekten.

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> Repository menüpontot.
2. Nyissuk ki a Branch defaults szekciót.
3. A legördülő menüből válasszuk ki a develop branchet.
4. Az Auto-close referenced issues on default branch opciót pipáljuk be.
5. Kattintsunk a Save changes gombra.

Default branch beállítása

3.2 A protected branchek beállítása

3.2.1 Alapbeállítások

Alapbeállítások

Az itt található konfigurációt, amennyiben az fent leírt módon importáljuk a projektet, akkor nem kell végrehajtanunk, de érdemes ellenőriznünk, hogy a leírtaknak megfelelő beállításokat látjuk-e a projekten.

Importált push/merge jogok törlése

Az import következtében, az importálást végző felhasználó alapértelmezetten be lesz állítva a develop és main branchekhez. Ezt a felhasználót az projekt indulásánál vegyük ki a push/merge joggal rendelkező felhasználók közül develop és main brancheknél.

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> Repository menüpontot.
2. Nyissuk ki a Protected branches szekciót.

3. A Protect a branch form segítségével adjuk hozzá a brancheket az alábbi táblázat alapján:

   Branch	Allowed to merge	Allowed to push	Allowed to force push	Code owner approval
   main	no one	no one	false	false
   develop	maintainers	no one	false	false
   release/*	maintainers	maintainers	false	false
   hotfix/*	maintainers	maintainers	false	false
   epic/*	maintainers	maintainers	false	false

   Ha mindent jól csináltunk az alábbi eredményt kell látnunk a Protected branches szekcióban:

   

3.2.2 Group Access Token user push/merge jog beállítása a protected branchekhez

Ahhoz, hogy a release job képes legyen a release kiadása után a release brancheket visszamergelni a védett develop és main branchekre, az alábbi beállításokat el kell végeznünk az összes projekten:

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> Repository menüpontot.
2. Nyissuk ki a Protected branches szekciót.

3. A develop és a main brancheken hajtsuk végre az alábbi lépéseket:

   1. Az Allow to push and merge oszlopban nyissuk ki a legördülő menüt, majd a keresőbe kezdjük el begépelni a Group Access Token létrehozása szekcióban létrehozott token nevét.
   2. Válasszuk ki az Accesss Tokenhez tartozó user-t, ezzel hozzádva azon felhasználókhoz, akik pusholhatnak a branch-re.

   

3.3 Merge requestek konfigurálása

Merge requestek konfigurálása

Az itt található konfigurációt, amennyiben az fent leírt módon importáljuk a projektet, akkor csak a Squash commits when merging bekezdéshez tartozó konfigurációt kell elvégeznünk, de érdemes a többi beállítást is ellenőriznünk.

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> Merge request menüpontot.

2. A Merge method bekezdésnél válasszuk ki a Fast-forward merge opciót.

   

3. A Squash commits when merging bekezdésnél válasszuk ki Encourage opciót.

   

4. A Merge checks bekezdésnél pipáljuk be a Pipelines must succeed és az All discussions must be resolved opciókat.

   

3.4 Continous Integration konfigurálása

3.4.1 Instance runnerek kikapcsolása

Instance runnerek kikapcsolása

Az itt található konfigurációt, amennyiben az fent leírt módon importáljuk a projektet, akkor nem kell végrehajtanunk, de érdemes ellenőriznünk, hogy a leírtaknak megfelelő beállításokat látjuk-e a projekten.

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> CI/CD menüpontot.
2. Nyissuk ki a Runners szekciót.

3. Az Instance Runners bekezdésben kapcsoljuk ki az instance runnert az Enable instance runners for this project opció disabledre állításával. Helyét az autoscaling manager veszi át automatikusan, mint group runner. Az autoscaling managerről részletesebben itt olvashatsz.

   

3.4.2 Job token permissions bekapcsolása

Az alábbi konfigurációs lépéseket az alábbi projektre hajtsuk végre:

• api
• backend
• frontend

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> CI/CD menüpontot.
2. Nyissuk ki a Job token permissions szekciót.

3. Az Limit access to this project kapcsolót állítsuk bekapcsolt állapotba.

   

Az alábbi konfigurációs lépéseket csak az api projektre hajtsuk végre.

1. Az api projektbe navigálva a baloldali menüsorból válasszuk ki a Settings -> CI/CD menüpontot.
2. Nyissuk ki a Job token permissions szekciót.
3. Az Allow CI job tokens from the following projects to access this project táblázat jobb felső sarkában kattintsunk az Add project or group gombra.

4. Az input mezőbe adjuk meg a backend projekt elérési útvonalát: gbsolutions/${projekt-nev}/backend, majd kattintsunk az Add gombra.

   

5. Ugyanígy adjuk hozzá a frontend projektet is.

3.4.3 Scheduled pipeline konfigurálása

Annak érdekében, hogy ne kelljen minden egyes job futása során letölteni ugyanazokat a maven/npm függőségeket, a recreate-caches job naponta egyszer lefut, és feltölti ezeket a függőségeket egy .zip archív fájlban a GitLab szerverre. Ezt a fájlt a megfelelő jobok induláskor letöltik és felhasználják.

Az alábbi konfigurációs lépéseket az következő projektre hajtsuk végre:

• backend
• frontend

1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Build -> Pipeline schedules menüpontot.

2. A Schedules képernyőn a recreate-caches sorban, jobb oldalt kattintsunk a „ceruza“ inkonra.

   

3. Az így megnyíló Edit Pipeline Schedules képernyőn pipáljuk be az Activated opciót, majd kattintsunk a Save pipeline schedule gombra.

   

4. Tagok hozzáadása

A repositoryk létrehozásakor a láthatóságnál szándékosan a Private opciót választottuk. Ennek oka, hogy explicit lehessen definiálni, hogy mely csapattagok milyen projektekhez férhessenek hozzá.

Ebből következően a projekten egyénenként kell eldönteni azt is, hogy projekt vagy subgroup szinten akarjuk hozzáadni az egyes tagokat.

Ezt az alapján lehet eldönteni, hogy mi a célunk:

• A hozzáadni kívánt csapattag csak bizonyos projektekhez férjen hozzá.
• A hozzáadni kívánt csapattag a subgroup alatti összes projekthez hozzáférjen.

Új tag hozzáadása:

1. Az aktuális projektbe/subgroupba navigálva a baloldali menüsorból válasszuk ki a Project information -> Members (Subgroup information -> Members subgroup scope esetén) menüpontot.
2. A jobb felső sarokban kattintsunk az Invite members gombra.
3. A GitLab member or email address adjuk meg a meghívni kívánt csapattag céges email címét.
4. A Select a role szekcióban válasszuk ki milyen jogosultsággal kell rendelkeznie az új tagnak.
5. Az Access expiration date szekcióban megadhatjuk meddig legyen hozzáférése az új tagnak a projekthez/subgrouphoz. (Amennyiben nem töltjük ki nem fog lejárni a hozzáférése.)
6. Kattintsunk az Invite gombra az új tag meghívásához.