Architektura rozwiązania

GitLab CI

GitLab CI (Continuous Integration) to wbudowany w GitLab system automatyzacji procesów budowania, testowania i wdrażania kodu.

GitLab

🔗 Repozytorium

Repozytorium procesów do ciągłej integracji i dostarczania (CI/CD) dla projektów

Workflow

Reguły uruchamiania pipeline zdefiniowane są w common/workflow/main.yml. Na podstawie zdarzenia GitLab ustawiane są zmienne PIPELINE_TYPE i ARTIFACTS_TYPE, które sterują regułami wykonania jobów.

workflow

Priorytet	Warunek	`PIPELINE_TYPE`	`ARTIFACTS_TYPE`
1	Tag `$CI_COMMIT_TAG` istnieje	`CD`	—
2	MR otwarty, nie jest Draft	`CI`	`snapshot`
3	Push na domyślną gałąź (main)	`CI`	`release`
4	Push na dowolną inną gałąź	`CI`	`snapshot`
fallback	Żaden warunek nie spełniony	—	pipeline nie powstaje

Struktura katalogów

flows/gitlab/
├── .gitlab-ci.yml                # Główny orkiestrator
├── common/                       # Wspólne komponenty dla wszystkich technologii
│   ├── .gitlab-ci.yml            # Orkiestrator common (includuje komponenty + instancje jobów)
│   ├── artifacts/main.yml        # Definicje artefaktów per job
│   ├── cache/main.yml            # Definicje cache per job
│   ├── helpers/                  # Współdzielone funkcje pomocnicze (logo, logger, job-prepare, job-docs, gitlab-tools)
│   ├── images/main.yml           # Obrazy Docker per job
│   ├── jobs/                     # Joby (wzorzec Job Capsule)
│   ├── needs/main.yml            # Zależności między jobami (DAG)
│   ├── resource_group/main.yml   # Grupy zasobów
│   ├── rules/main.yml            # Reguły wykonania per job
│   ├── stages/main.yml           # Definicja stagów
│   ├── variables/main.yml        # Zmienne globalne i per job
│   └── workflow/main.yml         # Reguły uruchamiania pipeline (PIPELINE_TYPE)
├── pipelines/                    # Szablony specyficzne dla technologii
│   ├── default/                  # Domyślny pipeline (gdy PROJECT_TYPE nie ustawiony)
│   ├── image-builder/            # Budowa obrazów kontenerów (Buildah)
│   ├── gitlab-pipelines/         # Pipeline CI/CD dla projektów GitLab
│   ├── gitlab-profile/           # Profile GitLab (zarządzanie pipeline meta)
│   ├── ansible-playbook/         # Zarządzanie i execucja Ansible playbook'ów
│   ├── ansible-role/             # Role Ansible — walidacja i linting
│   ├── opentofu-module/          # Moduły OpenTofu/Terraform
│   └── opentofu-iac/             # Infrastruktura OpenTofu/Terraform (IaC)
├── tests/                        # Walidacja
├── tools/                        # Skrypty generujące (create-job.sh, create-ci-technology.sh)
└── docs/                         # Dokumentacja dla developerów

Wzorzec joba

Każdy job istnieje w dwóch warstwach: common definiuje domyślną implementację, a pipeline technologii może ją nadpisać przez własny main.yml z identyczną nazwą klucza YAML.

job-capsule

Stages (common/stages/main.yml)

CI: prepare → validate → dependency → build → tests → publish
CD: prepare → validate → dependency → deployment → tests → publish

Stage	Przeznaczenie	CI/CD
`prepare` (`.pre`)	Wyznaczenie wersji (dry-run semantic-release) + przygotowanie deployment	CI/CD
`validate`	Walidacja konwencji i składni (conventional-commits, yamllint, shellcheck)	CI
`dependency`	Instalacja zależności	CI
`build`	Budowa artefaktów (obraz, paczka)	CI
`deployment`	Wdrożenie na środowiska	CD
`tests`	Testy jednostkowe	CI
`publish`	Publikacja artefaktów i finalny semantic-release	CI

Wzorzec Job Capsule

Każdy job to samodzielny katalog zawierający wszystkie pliki potrzebne do jego działania. Podział na osobne pliki .sh.yml jest zalecany przy dużych skryptach — pozwala utrzymać czytelność i umożliwia selektywne nadpisywanie przez technologie.

common/jobs/{nazwa-joba}/
├── main.yml                # Definicja joba (stage, image, rules, needs, artifacts)
├── script.sh.yml           # Główny skrypt joba
├── validate.sh.yml         # Walidacja parametrów wejściowych
├── before_script.sh.yml    # Setup przed uruchomieniem
├── after_script.sh.yml     # Cleanup po zakończeniu
└── README.md               # Dokumentacja dla użytkownika

Job w main.yml odwołuje się do komponentów common/ przez !reference:

.common.{job}.before_script.sh:
  - critical "Brak implementacji!"

.common.{job}.validate.sh:
  - warn "Brak implementacji!"

.common.{job}.script.sh:
  - critical "Brak implementacji!"

.common.{job}.after_script.sh:
  - critical "Brak implementacji!"

.common.{job}:
  image:     !reference [.common.images, {job}]
  stage:     !reference [.common.stages, {job}]
  variables: !reference [.common.variables, {job}]
  rules:     !reference [.common.rules, {job}]
  needs:     !reference [.common.needs, {job}]
  artifacts: !reference [.common.artifacts, {job}]
  cache:     !reference [.common.cache, {job}]

Obiekty Common

Plik	Klucz YAML	Co przechowuje
`artifacts/main.yml`	`.common.artifacts`	Co job produkuje (ścieżki, czas retencji)
`cache/main.yml`	`.common.cache`	Strategia cache per job
`images/main.yml`	`.common.images`	Obraz Docker dla każdego joba
`needs/main.yml`	`.common.needs`	DAG zależności między jobami
`resource_group/main.yml`	`.common.resource_group`	Grupy zasobów (np. deployment per environment)
`rules/main.yml`	`.common.rules`	Reguły wykonania per job
`stages/main.yml`	`.common.stages`	Przypisanie stagów per job
`variables/main.yml`	`.common.variables`	Zmienne wejściowe joba

Wzorzec Technologii

Każda technologia jest samowystarczalna — ma własne kopie obiektów z prefiksem .pipelines.{tech}.*:

pipelines/{tech}/
├── .gitlab-ci.yml          # Orkiestrator — instancje jobów
├── artifacts/main.yml      # .pipelines.{tech}.artifacts
├── cache/main.yml          # .pipelines.{tech}.cache
├── helpers/                # Lokalne aliasy helperów common
├── images/main.yml         # .pipelines.{tech}.images
├── needs/main.yml          # .pipelines.{tech}.needs
├── resource_group/main.yml # .pipelines.{tech}.resource_group
├── rules/main.yml          # .pipelines.{tech}.rules
├── stages/main.yml         # .pipelines.{tech}.stages
├── variables/main.yml      # .pipelines.{tech}.variables
└── jobs/
    ├── conventional-commits/ # Deleguje do .common.*
    ├── yamllint/             # Deleguje do .common.*
    ├── shellcheck/           # Deleguje do .common.*
    ├── versioning/           # Deleguje do .common.*
    ├── dependency/           # Deleguje do .common.* lub logika technologii
    ├── build/                # Logika specyficzna dla technologii
    ├── unit-test/            # Logika specyficzna dla technologii
    ├── publish/              # Logika specyficzna dla technologii
    ├── environment-deployment-prepare/ # Deleguje do .common.*
    ├── trigger-deployment/   # Deleguje do .common.*
    └── deployment/           # Logika specyficzna dla technologii