Gitlab Platform

Wstęp do Gitlab Platform

• 1: Gitlab-CI
• 1.1: Pipelines
• 1.1.1: Default
• 1.1.2: Gitlab CI
• 1.1.3: Gitlab Component
• 1.1.4: Image builder
• 1.1.5: docs
• 1.1.6: opentofu
• 1.1.7: opentofu module
• 1.1.8: renovate
• 1.2: Components
• 1.2.1: prepare
• 1.2.1.1: 🛠 Job template: Input Parameters
• 1.2.1.2: 🛠 Job template: Analyze Conventional Commits
• 1.2.2: validate
• 1.2.2.1: 🛠 Job template: 🔬 Validate files (conftest)
• 1.2.2.2: 🛠 Job template: 🕵 yamllint
• 1.2.3: release
• 1.2.3.1: 🛠 Job template: Publish Version
• 1.2.4: Application Security Testing
• 1.2.4.1: 🛠 Job template: 💪 SonarQube Scanner (SAST)
• 1.2.4.2: 🛠 Job template: 🔬 Trivy image scan (DAST)
• 1.2.5: containers
• 1.2.5.1: 🛠 Job template: 🚀 Image bulder
• 1.2.6: infrastructure
• 1.2.6.1: 🛠 Job template: OpenTofu
• 1.2.6.2: 🛠 Job template: Terraform
• 1.3: Definicja stages
• 1.4: ☠️ Wersjonowanie
• 2: 🌐 Gitlab pages
• 3: Conventional Commits

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s3["Repozytorium IAC"]
        n12["iac-gitlab"]
  end
 subgraph s4["Infrastruktura"]
        n13["Zarządzanie grupami i repozytoriami"]
  end
    n12 --> s4
    s4 --> n14["Repository"] & n15["Group"]
    n12@{ shape: rounded}
     n14:::Pine
     n15:::Pine
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF

1 - Gitlab-CI

Infrastruktura procesów gitlab-ci

Pipeline składa się z jobów (zadań) pogrupowanych w stage (etapy), np. build, test, deploy. GitLab CI uruchamia je w określonej kolejności, a wykonanie może odbywać się na GitLab Runnerach – agentach uruchamiających zadania.

Dzięki GitLab CI/CD możliwe jest ciągłe dostarczanie (CD), czyli automatyczne wdrażanie aplikacji na produkcję lub do środowisk testowych. Obsługuje kontenery, chmury i infrastruktury on-premise, ułatwiając zarządzanie cyklem życia oprogramowania.

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s5["Przestrzeń CI/CD"]
        n18["gitlab-ci"]
        n19["components"]
  end
    n18 --> n19
    s5 --> n11["containers"]
    n11 --> n22["Job"]
    n23["Run pipeline"] --> s5
    n24["Event"] --> n23
    n18@{ shape: rect}
    n19@{ shape: procs}
    n11@{ shape: procs}
    n22@{ shape: lean-r}
    n23@{ shape: in-out}
    n24@{ shape: event}
     n22:::Pine
     n23:::Pine
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF

Architektura projektu gitlab-ci w pl.rachuna-net/cicd

Projekt zawiera

pl.rachuna-net/cicd
├─ gitlab-ci                 # repozytorium z generycznymi procesami ci
├─ gitlab-profile            # Dokumentacja techniczna
└─ components                # grupa zawierająca komponenty (`ci/cd catalog`)
    ├── ast                  # Komponent do analizy pod kątem bezpiecezństwa (Application Security Testing).
    ├── containers           # Komponent odpowiedzialny za budowanie i publikacje kontenerów.
    ├── infrastructure       # Komponent odpowiedzialny za zarządzanie infrastrukturą.
    ├── prepare              # Komponent do przygotowania procesu CI/CD.
    ├── release              # Komponent do zarządzania wersjami i publikacji bibliotek i aplikacji na środowiska produkcyjne
    └── validate             # Komponent do automatycznej walidacji jakości i poprawności kodu w procesach CI/CD.

Projekt jest podzielony na logiczne komponenty, z których każdy odpowiada za określony etap w procesie CI/CD. Oto główne katalogi i ich funkcje:

• components: Zawiera komponenty odpowiedzialne za różne zadania, takie jak analiza statyczna kodu (SAST), testy jednostkowe, walidacja konfiguracji, budowanie i publikowanie artefaktów.
• gitlab-ci: Zawiera konfiguracje pipeline’ów, w tym pliki YAML definiujące etapy i zadania.
• gitlab-profile: Dokumentacja i skrypty wspierające konfigurację GitLab CI/CD.

Dlaczego taki układ jest korzystny?

Taki podział projektu pl.rachuna-net/cicd zapewnia:

1. Czytelność i modularność

   • Każdy komponent ma jasno określoną odpowiedzialność (np. containers tylko dla kontenerów, validate tylko dla walidacji kodu).
   • Ułatwia to nowym członkom zespołu szybkie odnalezienie się w strukturze – nie muszą przeszukiwać jednego, wielkiego pliku .gitlab-ci.yml.

2. Reużywalność procesów

   • Komponenty działają jak katalog CI/CD – można je wielokrotnie wykorzystywać w różnych projektach.
   • Na przykład prepare lub release mogą być użyte zarówno w projekcie backendowym, jak i frontendowym, bez potrzeby pisania wszystkiego od nowa.

3. Łatwa konserwacja i rozwój

   • Modyfikacja lub poprawka w jednym komponencie (np. ast) nie wpływa bezpośrednio na inne procesy – minimalizuje to ryzyko przypadkowych błędów.
   • Komponenty można rozwijać niezależnie, wprowadzając nowe funkcjonalności w sposób kontrolowany.

4. Skalowalność

   • Wraz z rozwojem organizacji można dodawać kolejne komponenty (np. performance-tests, security-audit) bez przebudowy całej architektury.
   • Każdy komponent może być utrzymywany przez inny zespół lub osobę, co umożliwia równoległy rozwój.

5. Standaryzacja procesów

   • Dzięki centralizacji komponentów wszystkie projekty w organizacji korzystają z tych samych procedur CI/CD, co zwiększa spójność i przewidywalność procesów.
   • Aktualizacja standardów (np. zmiana polityki wersjonowania w release) jest natychmiast dostępna dla wszystkich projektów.

6. Łatwe wdrożenie nowych projektów

   • Aby dodać CI/CD do nowego repozytorium, wystarczy włączyć potrzebne komponenty z katalogu – nie trzeba od zera pisać pipeline’ów.

Wady i ograniczenia takiego układu

Choć architektura oparta na modułowych komponentach CI/CD ma wiele zalet, wiąże się też z pewnymi wyzwaniami. Wymaga dyscypliny w utrzymaniu zgodności wersji komponentów pomiędzy projektami, aby uniknąć sytuacji, w której różne repozytoria korzystają z niekompatybilnych wersji tego samego procesu. Centralizacja logiki powoduje również, że błąd w jednym komponencie może wpłynąć na wiele projektów jednocześnie, jeśli zostanie wdrożony bez odpowiedniego testowania. Dodatkowo w większych organizacjach może pojawić się konieczność koordynacji prac między zespołami rozwijającymi poszczególne komponenty, co może spowalniać wdrażanie zmian.

1.1 - Pipelines

Lista pielines

Poniżej znajduje się lista stworzonych procesów

1.1.1 - Default

Default

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

1.1.2 - Gitlab CI

gitlab-ci

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

1.1.3 - Gitlab Component

gitlab-component

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

1.1.4 - Image builder

Image builder

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["prepare"]
        n1["🔍 Analyze Conventional Commits"]
        n2["⚙️ Input Parameters"]
        n3["🕵 Set Version"]
  end
 subgraph s2["validate"]
        n4["🧪 Validate files (conftest)"]
        n11@{ label: "<div style=\"color:\"><span style=\"color:\">🧑‍💻 YAML lint</span></div>" }
  end
 subgraph s3["build"]
        n5["🚀 build container image"]
  end
 subgraph s4["publish"]
        n6["🌐 publish container image"]
  end
 subgraph s5["release"]
        n8["📍 Publish Version"]
  end
 subgraph s6["integration-test"]
        n9["🔬 trivy (dast)"]
        n10["🧪 test docker image"]
  end
    s1 --> s2
    s2 --> s3
    s3 --> s4
    s4 --> s5
    s5 --> s6
    n1 --- n2
    n2 --- n3
    n9 --- n10
    n4 --> n11
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/set_version.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/contrest.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/trivy.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"

1.1.5 - docs

docs

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/sast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

1.1.6 - opentofu

OpenTofu

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n9@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu validate</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
 subgraph s5["unit-test"]
        n12@{ label: "<span style=\"color:\" color=\"\">🧪 opentofu plan</span>" }
  end
 subgraph s6["deploy"]
        n13@{ label: "<span style=\"color:\" color=\"\">💥 opentofu apply</span>" }
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s5
    n1 --- n8
    n8 --> n9
    n9 --> n10
    n10 --> n11
    s5 --> s3
    s4 --> s6

    n8@{ shape: rect}
    n9@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    n12@{ shape: rect}
    n13@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n12 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n13 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"

1.1.7 - opentofu module

OpenTofu Module

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">terraform-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    n1 --- n8
    n8 --- n10
    n10 --- n11
    s1 --> s3
    n8@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components//-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

1.1.8 - renovate

renovate

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/sast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

1.2 - Components

Lista komponentów

Poniżej znajduje się lista stworzonych komponentów

component	version
ast
build
deploy
prepare
release
sast
unit-test
validate

1.2.1 - prepare

1.2.1.1 - 🛠 Job template: Input Parameters

Job, który wyświetla informacje o zmiennych procesowych CI

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Komponent wypisuje wartości m.in. następujących zmiennych:

• GITLAB_CI_VERSION
• COMPONENT_VERSION_*
• COMPONENT_VERSION_DEPLOY
• CONTAINER_IMAGE_*
• CONTAINER_IMAGE_PYTHON
• VAULT_ADDR
• SONAR_HOST_URL

📤 Output

Skrypt wypisuje dane w formie tabeli ASCII w logach pipeline’u, np.:

===> 💾 Print set inputs Variables
┌────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Variable                       │ Value                                                                                               │
├────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ CONTAINER_IMAGE_TERRAFORM      │ registry.gitlab.com/pl.rachuna-net/containers/terraform:1.0.0                                       │
│ COMPONENT_VERSION_DEPLOY       │ v1.2.3                                                                                              │
...
└────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘

🧪 Przykład użycia

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/prepare/input_parameters@$COMPONENT_VERSION_PREPARE
    inputs:
      docker_image: $CONTAINER_IMAGE_PYTHON

🔍 input parameters:
  stage: prepare
  rules:
    - when: on_success

1.2.1.2 - 🛠 Job template: Analyze Conventional Commits

🔍 Analyze Conventional Commits

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/prepare/conventional_commits@$COMPONENT_VERSION_PREPARE
    inputs:
      docker_image: $CONTAINER_IMAGE_PYTHON

🔍 Analyze Conventional Commits:
  stage: prepare
  rules:
    - when: on_success

1.2.2 - validate

1.2.2.1 - 🛠 Job template: 🔬 Validate files (conftest)

Wymagania wstępne

• conftest

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_CONFTEST – obraz Dockera Conftest (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• REPOSITORY_POLICIES – repozytorium z politykami
• REPOSITORY_POLICIES_BRANCH – branch repozytorium z politykami
• REPOSITORY_POLICIES_PATH – katalog polityk w repozytorium
• SOURCE_FILES – pliki do testowania
• NAMESPACE_POLICY – przestrzeń nazw polityk Conftest

📤 Output

Job wykonuje następujące kroki:

1. Pobranie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o przekazanych parametrach (_function_print_row).
3. Klonowanie repozytorium z politykami (repository_policies) w odpowiednim branchu.
4. Uruchomienie Conftest z wykorzystaniem wskazanych plików (source_files) i polityk (repository_policies_path) w przestrzeni nazw namespace_policy.

Przykład logu:

===> 🔬 Conftest Validate - Parameters
┌───────────────────────────────────┬─────────────────────────────────────────────────────┐
│ Variable                          │ Value                                               │
├───────────────────────────────────┼─────────────────────────────────────────────────────┤
│ REPOSITORY_POLICIES               │ git@gitlab.com:pl.rachuna-net/discipline.git        │
│ REPOSITORY_POLICIES_PATH          │ policies/conftest                                   │
│ SOURCE_FILES                      │ *.yml                                               │
└───────────────────────────────────┴─────────────────────────────────────────────────────┘

🧪 Dostępne joby

🔬 Validate files (conftest)

Waliduje wskazane pliki repozytorium względem polityk Conftest:

🔬 Validate files (conftest):
  stage: validate
  image: $CONTAINER_IMAGE_CONFTEST
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.validate:_function_print_row]
    - !reference [.validate:conftest_input_variables]
    - !reference [.validate:conftest_prepare]
  script:
    - conftest test $SOURCE_FILES --policy $REPOSITORY_POLICIES_PATH --namespace $NAMESPACE_POLICY

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/validate/conftest@$COMPONENT_VERSION_VALIDATE
    inputs:
      repository_policies: git@gitlab.com:pl.rachuna-net/discipline.git
      repository_policies_path: policies/k8s
      source_files: "config.yml"
      namespace_policy: image_builder

⚡ Dzięki temu szablonowi szybko weryfikujesz zgodność konfiguracji z politykami OPA/Conftest bez ręcznej konfiguracji za każdym razem w pipeline’ach.

1.2.2.2 - 🛠 Job template: 🕵 yamllint

Job, który wykonuje walidację składni plików YAML w repozytorium przy użyciu narzędzia yamllint.

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Job ustawia i wykorzystuje poniższe zmienne środowiskowe:

• CONTAINER_IMAGE_PYTHON – wybrany obraz Dockera.
• LOGO_URL – adres logotypu, który jest opcjonalnie pobierany w trakcie uruchamiania joba.
• VALIDATE_REPO_NAMESPACE – namespace repozytorium komponentu validate.
• VALIDATE_REPO_BRANCH – gałąź repozytorium komponentu validate.
• YAMLLINT_PATH – ścieżka do pliku konfiguracyjnego yamllint.

📤 Output

Job wykonuje linting plików YAML i wypisuje wyniki w logach pipeline’u w formie standardowej dla narzędzia yamllint, np.:

===> 🔍 YAML lint results
source/ci-template.yml
  10:3      warning  missing document start "---"  (document-start)
  22:1      error    too many blank lines (1 > 0)  (empty-lines)

W przypadku błędów job kończy się statusem failed.

1.2.3 - release

1.2.3.1 - 🛠 Job template: Publish Version

Wersjonowania kodu

Job, który odpowiada za wersjonowanie i publikację zmian w repozytorium za pomocą narzędzia semantic-release. Szablon składa się z dwóch kroków:

1. 🕵 Set Version – ustawia wersję w trybie dry-run (przygotowanie).
2. 📍 Publish Version – publikuje nową wersję (release).

[!NOTE]

Wymagania:

• Obraz kontenera dostępny jest tutaj.
• Stosowanie standardu opisywania commitów Conventional Commits

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Job ustawia i wykorzystuje poniższe zmienne środowiskowe:

• CONTAINER_IMAGE_SEMANTIC_RELEASE – obraz Dockera z semantic-release.
• LOGO_URL – adres logotypu.
• DEBUG – flaga debugowania (dziedziczona z inputs.debug).
• VERSIONING_DEBUG – włącza dodatkowy debug semantic-release.
• VERSIONING_DRY_RUN – uruchamia semantic-release w trybie dry-run.
• COMPONENT_REPO_NAMESPACE – namespace repozytorium komponentu.
• COMPONENT_REPO_BRANCH – gałąź repozytorium komponentu.
• RELEASERC_FILE – ścieżka do pliku .releaserc.js.

📤 Output

Job generuje:

1. Plik CHANGELOG.md – zawierający opis zmian.

2. Plik versioning.env (zapisany jako artifact dotenv) z informacjami o wersji, np.:

   VERSION=1.2.3
   VERSION_MAJOR=1
   VERSION_MINOR=2
   VERSION_PATCH=3
   

3. Logi semantic-release z informacją o wygenerowanej wersji i ewentualnie o publikacji.

📝 Przykładowe użycie w pipeline

include:
  - component: '$CI_SERVER_FQDN/pl.rachuna-net/cicd/components/release@$COMPONENT_VERSION_RELEASE'
    inputs:
      docker_image: "registry.gitlab.com/pl.rachuna-net/containers/semantic-release:2.0.0"
      debug: "true"
      dry_run: "false"

🔎 Kroki joba

🕵 Set Version

• Stage: prepare
• Uruchamia semantic-release w trybie dry-run (VERSIONING_DRY_RUN: "true") w celu przygotowania wersji i changeloga.

📍 Publish Version

• Stage: release
• Uruchamia semantic-release w trybie pełnym (publikacja wersji i generacja changeloga).

Jak działa komponent?

Analiza brancha

W pierwszej kolejności sprawdzane jest - czy można zwersjonować aplikacje na odpowiednim branchu

"branches": [
    { 
      "name": "feature/*", 
      "channel": "feat-${name.replace(/^feature\\//, '').substring(0, 20)}", 
      "prerelease": "feat-${name.replace(/^feature\\//, '').substring(0, 20)}" 
    },
    { 
      "name": "epic/*", 
      "channel": "epic-${name.replace(/^epic\\//, '').replace(/[^A-Za-z0-9]/, '').substring(0, 20)}", 
      "prerelease": "epic-${name.replace(/^epic\\//, '').replace(/[^A-Za-z0-9]/, '').substring(0, 20)}" 
    },
    { "name": "alpha", "channel": "alpha", "prerelease": true },
    { "name": "release", "channel": "rc", "prerelease": true },
    { "name": "hotfix", "channel": "ht", "prerelease": true },
    { "name": "main" }
],

Sprawdzanie convensional commits

Komponent sprawdza, czy czyta wszystkie informacje o commitach zgodnie z standardem Conventional Commits

"plugins": [
[ "@semantic-release/commit-analyzer",
    {
        "preset": "conventionalcommits",
        "releaseRules": [
            { "breaking": true, "release": "major" },
            { "type": "feat", "release": "minor" },
            { "type": "fix", "release": "patch" },
            { "type": "style", "release": "patch" },
            { "type": "perf", "release": "patch" },
            { "type": "test", "release": "patch" },
            { "type": "docs", "release": "patch" },
            { "type": "sec", "release": "patch" }
        ]
    }
],

Generowanie releases notes

Następnie generuje release notes

[
    "@semantic-release/release-notes-generator",
    {
        "preset": "conventionalcommits",
        "presetConfig": {
            "types": [
              { "type": "feat", "section": "✨ Features ✨" },
              { "type": "fix", "section": "🐛 Bug Fixes 🐛" },
              { "type": "revert", "section": "⏮️️ Reverts ⏮️️" },
              { "type": "perf", "section": "🔧 Performance Improvements 🔧" },
              { "type": "docs", "section": "📝 Documentation 📝" },
              { "type": "build", "section": "📀 Build 📀" },
              { "type": "test", "section": "💚 Tests 💚" },
              { "type": "ci", "section": "🏁 CI/CD 🏁" }
            ]
        }
    }
],

Generowanie chandelog.md

Generowanie localnie pliku CHANGELOG.md

[
    "@semantic-release/changelog",
    {
      "changelogFile": "CHANGELOG.md"
    }
],

Integracja z gitlab

Integracja z gitab

[
    "@semantic-release/gitlab"
]

Ustawienie zmiennych środowiskowych

{
  name: "versioning-variables",
  generateNotes: (pluginConfig, context) => {
    const releaseNote = context.nextRelease.notes;
    const nextVersion = context.nextRelease.version;

    // Check if the version is a final version or a snapshot
    const finalVersionRegex = /(\d+\.\d+\.\d+)/;
    const matchFinalVersion = nextVersion.match(finalVersionRegex);
    let artifactType = "snapshot";
    if (matchFinalVersion) {
      artifactType = "release";
    }

    // Extract JIRA issues from commits
    const jiraRegexp = /\b[A-Z][A-Z0-9_]+-[1-9][0-9]*/g;
    const jiraSet = new Set();

    for (const commit of context.commits) {
      if (commit.message) {
        const matchJIRA = commit.message.match(jiraRegexp);
        if (matchJIRA) {
          matchJIRA.forEach(jira => jiraSet.add(match));
        }
      }
    }

    // Create a file with the environment variables
    const uniqJiraList = Array.from(jiraSet)
    const environmentList = [
      { key: "RELEASE_CANDIDATE_VERSION", value: nextVersion },
      { key: "ARTIFACTS_TYPE", value: artifactType },
      { key: "JIRA_ISSUES_IDS", value: uniqJiraList.join(", ") }
    ]
    const fileContent = environmentList.map(env => `${env.key}=${env.value}`).join("\n");
    fs.writeFileSync("versioning.env", fileContent);
  }
}

Linki

• SemVer
• semantic-release

1.2.4 - Application Security Testing

- Application Security Testing

1.2.4.1 - 🛠 Job template: 💪 SonarQube Scanner (SAST)

Wymagania wstępne

• SonarQube Scanner – dostępny w obrazie Dockera ustawianym przez inputs.docker_image.
• Skonfigurowane konto w SonarCloud lub własnej instancji SonarQube (parametry: sonar_host_url, sonar_token, sonar_project_key).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_SONAR_SCANNER – obraz Dockera SonarQube Scanner (na podstawie inputs.docker_image)
• SONAR_USER_HOME – katalog roboczy SonarQube
• SONAR_HOST_URL – adres instancji SonarQube/SonarCloud
• SONAR_ORGANIZATION – nazwa organizacji
• SONAR_PROJECT_KEY – klucz projektu w SonarQube
• SONAR_PROJECT_NAME – nazwa projektu
• SONAR_PROJECT_DESCRIPTION – opis projektu
• SONAR_PROJECT_VERSION – wersja projektu
• SONAR_SOURCES – ścieżki źródeł do analizy
• SONAR_TOKEN – token uwierzytelniający do SonarQube

📤 Output

Job wykonuje następujące kroki:

2. Wyświetlenie zmiennych wejściowych i konfiguracji SonarQube.

3. Uruchomienie SonarQube Scanner z zadeklarowanymi parametrami:

   • analiza kodu z podanych źródeł (SONAR_SOURCES),
   • przesłanie wyników do wskazanej instancji (SONAR_HOST_URL).

Pipeline zakończy się niepowodzeniem, jeśli analiza SonarQube wykryje błędy jakościowe powodujące blokadę (quality gate failure).

🧪 Dostępny job

💪 sonarqube scanner (sast)

Analizuje kod źródłowy i przesyła wyniki do SonarQube/SonarCloud:

💪 sonarqube scanner:
  stage: sast
  image: $CONTAINER_IMAGE_SONAR_SCANNER
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.ast:_function_print_row]
    - !reference [.ast:sonarqube_input_variables]
    - !reference [.ast:sonarqube-init]
  script:
    - |
      sonar-scanner \
        -Dsonar.projectKey="${SONAR_PROJECT_KEY}" \
        -Dsonar.organization="${SONAR_ORGANIZATION}" \
        -Dsonar.projectName="${SONAR_PROJECT_NAME}" \
        -Dsonar.projectDescription="${CI_PROJECT_DESCRIPTION}" \
        -Dsonar.projectVersion="${SONAR_PROJECT_VERSION}" \
        -Dsonar.sources="${SONAR_SOURCES}" \
        -Dsonar.sourceEncoding=UTF-8 \
        -Dsonar.token="${SONAR_TOKEN}"
  rules:
    - when: on_success

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/ast/sonarqube@$COMPONENT_VERSION_SONARQUBE

💪 sonarqube scanner:
  variables:
    SONAR_PROJECT_KEY: $CI_PROJECT_NAME
    SONAR_PROJECT_NAME: "Project $CI_PROJECT_NAME"
    SONAR_TOKEN: $SONAR_TOKEN
  rules:
    - when: on_success

1.2.4.2 - 🛠 Job template: 🔬 Trivy image scan (DAST)

Wymagania wstępne

• Trivy – wbudowany w używany obraz Dockera (ustawiany przez inputs.docker_image).
• Obraz kontenera, który ma zostać przeskanowany (ustawiany przez inputs.container_to_analyze).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_TRIVY – obraz Dockera Trivy (na podstawie inputs.docker_image)
• CONTAINER_TO_ANALYZE – nazwa obrazu kontenera do przeskanowania (na podstawie inputs.container_to_analyze)
• TRIVY_NO_PROGRESS – wyłącza pasek postępu w logach (domyślnie true)
• TRIVY_CACHE_DIR – lokalny katalog cache Trivy (domyślnie .trivycache/)

📤 Output

Job wykonuje następujące kroki:

1. Uruchomienie skanowania obrazu kontenera (CONTAINER_TO_ANALYZE) z użyciem Trivy:

   • Najpierw wyszukiwanie luk o poziomie HIGH – raport ostrzegawczy (--exit-code 0).
   • Następnie wyszukiwanie luk o poziomie CRITICAL – pipeline zakończy się niepowodzeniem, jeśli takie wystąpią (--exit-code 1).

2. Wykorzystanie cache Trivy w katalogu .trivycache/ w celu przyspieszenia kolejnych skanów.

🧪 Dostępny job

🔬 trivy (dast)

Skanuje wskazany obraz kontenera i kończy pipeline, jeśli znajdzie luki o poziomie CRITICAL:

🔬 trivy (dast):
  image: $CONTAINER_IMAGE_TRIVY
  stage: integration-test
  services:
    - name: $CONTAINER_IMAGE_TRIVY
      alias: buildah-dind
  allow_failure: true
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.ast:trivy_input_variables]
  script:
    - trivy image --exit-code 0 --severity HIGH $CONTAINER_TO_ANALYZE
    - trivy image --exit-code 1 --severity CRITICAL $CONTAINER_TO_ANALYZE
  cache:
    paths:
      - .trivycache/

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/ast/trivy@$COMPONENT_VERSION_TRIVY

🔬 trivy (dast):
  allow_failure: true
  variables:
    CONTAINER_TO_ANALYZE: $CI_REGISTRY_IMAGE:$RELEASE_CANDIDATE_VERSION
  rules:
    - when: on_success

1.2.5 - containers

1.2.5.1 - 🛠 Job template: 🚀 Image bulder

Wymagania wstępne

• Buildah – wbudowany w używany obraz Dockera (ustawiany przez inputs.docker_image).
• Dostęp do rejestru Docker/GitLab (CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD).
• Plik konfiguracyjny obrazu kontenera (buildah_config_path).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_BUILDAH – obraz Dockera Buildah (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• CONTAINER_VERSION – wersja obrazu (na podstawie inputs.container_version)
• FULL_IMAGE_NAME – pełna nazwa obrazu: $CI_REGISTRY_IMAGE:$CONTAINER_VERSION
• BUILDAH_CONFIG_FILE_PATH – ścieżka do pliku konfiguracji Buildah (na podstawie inputs.buildah_config_path)
• DOCKER_TEST_SCRIPT_PATH – skrypt testowy do uruchomienia w kontenerze
• Dodatkowe zmienne konfiguracyjne Buildah: STORAGE_DRIVER, BUILDAH_FORMAT, BUILDAH_ISOLATION, BUILDAH_STORAGE_ROOT, BUILDAH_STORAGE_RUNROOT

📤 Output

Szablon wykonuje następujące kroki:

1. Budowanie obrazu kontenera na podstawie buildah_config_path:

   • Pobranie obrazu bazowego (base_image)
   • Instalacja pakietów i certyfikatów
   • Dodanie repozytoriów (custom_repos)
   • Kopiowanie plików i ustawienie zmiennych środowiskowych
   • Tworzenie użytkownika nie-root (opcjonalnie)
   • Ustawienie ENTRYPOINT oraz CMD

2. Zapis obrazu do tarballa (container-image.tar).

3. Publikacja obrazu w rejestrze Docker/GitLab (job 🌐 publish container image).

4. Testowanie obrazu z wykorzystaniem skryptu testowego (job 🧪 test docker image).

🧪 Dostępne joby

🚀 build container image

Buduje obraz kontenera na podstawie pliku konfiguracyjnego config.yml

Przykładowy plik config yml:

---
base_image: ubuntu:noble

labels:
  maintainer: "Maciej Rachuna <rachuna.maciej@gmail.com>"
  version: "1.0.0"
  image_source: "https://gitlab.com/pl.rachuna-net/containers/terraform"

env:
  DEBIAN_FRONTEND: noninteractive
  TF_IN_AUTOMATION: "true"
  LANG: C.UTF-8

before_build_commands:
  ## terraform docs
  - curl -sLo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.20.0/terraform-docs-v0.20.0-linux-amd64.tar.gz
  - tar -xzf terraform-docs.tar.gz
  - chmod +x terraform-docs
  ## terraform lint
  - curl -sLo ./tflint_linux_amd64.zip https://github.com/terraform-linters/tflint/releases/download/v0.58.1/tflint_linux_amd64.zip
  - unzip tflint_linux_amd64.zip
  - chmod +x tflint

packages:
  - bash
  - curl
  - git
  - gnupg2
  - jq
  - libssl3
  - lsb-release
  - openssh-client
  - ca-certificates
  - gnupg
  - terraform

custom_repos:
  - name: hashicorp
    key_url: https://apt.releases.hashicorp.com/gpg
    key_path: /usr/share/keyrings/hashicorp-archive-keyring.gpg
    repo_entry: >-
      deb [arch=amd64 signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg trusted=yes] https://apt.releases.hashicorp.com noble main

extra_commands:
  - chmod 777 /opt/scripts
  - chmod 777 /opt/scripts/*
  - terraform --version
  - terraform-docs -v
  - tflint --version

copy:
  - source: scripts/
    destination: /opt/scripts/
  - source: terraform-docs
    destination: /usr/local/bin/terraform-docs
  - source: tflint
    destination: usr/local/bin/tflint

user:
  name: nonroot
  shell: /bin/bash
  home: /home/nonroot
  chown: /opt/scripts/

entrypoint: "/opt/scripts/entrypoint.bash"
cmd: "/bin/bash"

🌐 publish container image

Publikuje zbudowany obraz do gitlab registry:

🧪 test docker image

Testuje opublikowany obraz kontenera uruchamiając w nim skrypt bashowy domyślnie container_test.sh:

🧪 Przykład użycia w pipeline

---
default:
  tags:
    - process-ci

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/containers/image-builder@$COMPONENT_VERSION_CONTAINERS


🚀 build container image:
  needs:
    - job: 🕵 YAML lint
      optional: true
    - job: 🔬 Validate files (conftest)
    - job: 🕵 Set Version
      artifacts: true
  stage: build
  rules:
    - when: on_success


🌐 publish container image:
  stage: publish
  variables:
    CONTAINER_VERSION: 1.2.3
  needs:
    - job: 🕵 Set Version
      artifacts: true
    - job: 🚀 build container image
      artifacts: true
  rules:
    - when: on_success


🧪 test docker image:
  variables:
    CONTAINER_VERSION: 1.2.3
  needs:
    - job: 📍 Publish Version
      artifacts: true
    - job: 🌐 publish container image
      artifacts: true
  rules:
    - when: on_success

1.2.6 - infrastructure

1.2.6.1 - 🛠 Job template: OpenTofu

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobach

Komponent ustawia następujące zmienne w środowisku CI:

• CONTAINER_IMAGE_OPENTOFU – obraz Dockera OpenTofu (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• TF_STATE_NAME – nazwa stanu OpenTofu
• TF_VAR_gitlab_token – token GitLab przekazywany do OpenTofu
• DEBUG – flaga debug

📤 Output

Joby wykonują:

1. Pobranie i wyświetlenie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o wejściowych parametrach.
3. Inicjalizację środowiska OpenTofu (tofu init) oraz odpowiednie akcje (fmt, validate, tflint, plan, apply).

Przykład logu:

===> 💾 OpenTofu Base Job - Parameters
┌──────────────────────────────┬───────────────────────────────────────────────────────┐
│ Variable                     │ Value                                                 │
├──────────────────────────────┼───────────────────────────────────────────────────────┤
│ TF_STATE_NAME                │ default                                               │
│ CONTAINER_IMAGE_OPENTOFU     │ registry.gitlab.com/pl.rachuna-net/...:2.0.0          │
└──────────────────────────────┴───────────────────────────────────────────────────────┘

🧪 Dostępne joby

🕵 opentofu fmt

Sprawdza formatowanie plików OpenTofu:

🕵 opentofu fmt:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu fmt -recursive -check

✅ opentofu validate

Wykonuje walidację konfiguracji OpenTofu:

✅ opentofu validate:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - !reference [.infrastructure:opentofu_init]
    - tofu validate

✅ tflint

Uruchamia lintera tflint:

✅ tflint:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - tflint

✅ terraform-docs

Generuje dokumentację modułu Terraform:

✅ terraform-docs:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform-docs md . > README.md

🧪 opentofu plan

Wykonuje plan wdrożenia OpenTofu:

🧪 opentofu plan:
  stage: unit-test
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu plan

💥 opentofu apply

Wdraża infrastrukturę OpenTofu:

💥 opentofu apply:
  stage: deploy
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu apply -auto-approve

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/infrastructure/opentofu@$COMPONENT_VERSION_INFRASTRUCTURE
    inputs:
      docker_image: $CONTAINER_IMAGE_OPENTOFU
      tf_state_name: production
      debug: "true"

1.2.6.2 - 🛠 Job template: Terraform

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobach

Komponent ustawia następujące zmienne w środowisku CI:

• CONTAINER_IMAGE_TERRAFORM – obraz Dockera Terraform (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• TF_STATE_NAME – nazwa stanu Terraform
• TF_VAR_gitlab_token – token GitLab przekazywany do Terraform
• DEBUG – flaga debug

📤 Output

Joby wykonują:

1. Pobranie i wyświetlenie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o wejściowych parametrach.
3. Inicjalizację środowiska Terraform (terraform init) oraz odpowiednie akcje (fmt, validate, tflint, plan, apply).

Przykład logu:

===> 💾 Terraform Base Job - Parameters
┌──────────────────────────────┬───────────────────────────────────────────────────────┐
│ Variable                     │ Value                                                 │
├──────────────────────────────┼───────────────────────────────────────────────────────┤
│ TF_STATE_NAME                │ default                                               │
│ CONTAINER_IMAGE_TERRAFORM    │ registry.gitlab.com/pl.rachuna-net/...:2.0.0          │
└──────────────────────────────┴───────────────────────────────────────────────────────┘

🧪 Dostępne joby

🕵 terraform fmt

Sprawdza formatowanie plików Terraform:

🕵 terraform fmt:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform fmt -recursive -check

✅ terraform validate

Wykonuje walidację konfiguracji Terraform:

✅ terraform validate:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - !reference [.infrastructure:terraform_init]
    - terraform validate

✅ tflint

Uruchamia lintera tflint:

✅ tflint:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - tflint

✅ terraform-docs

Generuje dokumentację modułu Terraform:

✅ terraform-docs:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform-docs md . > README.md

🧪 terraform plan

Wykonuje plan wdrożenia Terraform:

🧪 terraform plan:
  stage: unit-test
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform plan

💥 terraform apply

Wdraża infrastrukturę Terraform:

💥 terraform apply:
  stage: deploy
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform apply -auto-approve

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/infrastructure/terraform@$COMPONENT_VERSION_INFRASTRUCTURE
    inputs:
      docker_image: $CONTAINER_IMAGE_TERRAFORM
      tf_state_name: production
      debug: "true"

1.3 - Definicja stages

Definicja stages

Przykładowa zawartość pliku:

---
stages:
    ### Standard w ramach dyscypliny
    - prepare           # przygotowanie środowiska, instalacja zależności, inicjalizacja.
    - dependency        # pobieranie zależności (biliotek, funkcji, komponentów)
    - validate          # weryfikacja poprawności konfiguracji, linting, planowanie zmian (Terraform, Ansible), pre-commit checks.
    - unit-test         # testy jednostkowe dla kodu (Go, .NET, Node.js itp.).
    - sast              # analiza statyczna kodu (Static Application Security Testing).
    - dast              # analiza dynamiczna aplikacji (Dynamic Application Security Testing).
    - build             # budowanie artefaktów (Packer, kontenery, kod źródłowy).
    - publish           # publikacja artefaktów, obrazów kontenerowych, paczek NuGet, npm itp.
    - release           # Wydawanie wersji
    - deploy            # wdrażanie aplikacji, infrastruktury, konfiguracji.
    - integration-test  # testy integracyjne, e2e, testy akceptacyjne.
    - cleanup           # usuwanie tymczasowych zasobów, sprzątanie środowiska.

1.4 - ☠️ Wersjonowanie

Definicja stages

Racja – poprzednia odpowiedź była bardziej ogólna niż powinna. Skupmy się teraz na technicznej dokumentacji wersjonowania dokładnie w kontekście Twojego rysunku. Oto spójny opis, który możesz wkleić do dokumentacji:

Wersjonowanie w projekcie

W projekcie wykorzystujemy semantic-release do w pełni zautomatyzowanego nadawania wersji, tagowania oraz generowania changeloga. Proces opiera się na strukturze gałęzi main / develop / feature oraz na konwencji commitów (Conventional Commits).

1. Gałęzie w repozytorium

1. main – zawiera stabilne wydania produkcyjne.

   • Każdy merge z develop powoduje wygenerowanie pełnego release (1.0.0, 1.1.0 itd.).

2. develop – zawiera kod przeznaczony do testów wewnętrznych.

   • Każdy merge z gałęzi feature powoduje wygenerowanie pre-release (1.1.0-dev.1, 1.1.0-dev.2 itd.).

3. Gałęzie funkcjonalne (feat/<JIRA-ID>) – zawierają zmiany pojedynczych funkcjonalności.

   • Nie generują wersji samodzielnie.
   • Wersja jest podbijana dopiero po merge do develop.

2. Jak semantic-release nadaje wersje?

• Semantic-release analizuje commity od ostatniego taga.

• Na podstawie typów commitów automatycznie decyduje o nowej wersji:

  • fix: / chore: – patch (np. 1.0.0 → 1.0.1)
  • feat: – minor (np. 1.0.0 → 1.1.0)
  • BREAKING CHANGE: – major (np. 1.0.0 → 2.0.0)

• Dla develop każda zmiana jest oznaczana jako pre-release z przyrostowym numerem dev:

  1.1.0-dev.1
  1.1.0-dev.2
  

• Merge develop → main tworzy pełny release:

  1.1.0
  

3. Przykład na podstawie diagramu

1. Tag 1.0.0 istnieje na gałęzi main.

2. Tworzymy gałąź develop – kolejne zmiany są tu wersjonowane jako pre-release:

   • Merge feat/JIRA-1234 → develop: wersja 1.1.0-dev.1
   • Merge feat/JIRA-2345 → develop: wersja 1.1.0-dev.2

3. Gdy kod na develop jest stabilny:

   • Merge do main → semantic-release tworzy pełny release: wersja 1.1.0 oraz changelog.

4. Konfiguracja (.releaserc)

{
  "branches": [
    "main",
    { "name": "develop", "prerelease": "dev" }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/gitlab"
  ]
}

• Gałąź main generuje pełne wydania.
• Gałąź develop generuje pre-release z dopiskiem -dev.X.

Czy chcesz, żebym przygotował wersję dokumentacji z diagramem w SVG/PNG, gdzie będzie oznaczony każdy krok (merge, tag, pre-release)? Mogę też dodać sekcję o commitach (wzorce feat, fix itd.) albo schemat krok-po-kroku pipeline’u CI/CD (np. GitLab CI). Chcesz, żeby to była pełna sekcja “Wersjonowanie” w stylu dokumentacji technicznej projektu?

gitGraph
        commit id: "latest" tag: "1.0.0"
        branch "develop"
        branch "feat/JIRA-1234"
        branch "feat/JIRA-2345"
        checkout "develop"
        checkout "feat/JIRA-1234"
        commit id: "feat: JIRA-1234"
        checkout develop
        merge "feat/JIRA-1234" id: "FEAT-1234" tag: "1.1.0-dev.1"
        checkout main
        checkout "feat/JIRA-2345"
        commit id: "fix: JIRA-2345"
        checkout develop
        merge "feat/JIRA-2345"  id: "FEAT-2345" tag: "1.1.0-dev.2"
        checkout main
        merge "develop" id: "New Version" tag: "1.1.0"

gitGraph
        commit id: "latest" tag: "1.0.0"
        branch "develop"
        branch "feat/JIRA-1234"
        branch "feat/JIRA-2345"
        checkout "develop"
        checkout "feat/JIRA-1234"
        commit id: "feat: JIRA-1234"
        checkout develop
        merge "feat/JIRA-1234" id: "FEAT-1234" tag: "1.0.0-dev.1"
        checkout main
        checkout "feat/JIRA-2345"
        commit id: "feat: JIRA-2345"
        checkout develop
        merge "feat/JIRA-2345"  id: "FEAT-2345" tag: "1.0.0-dev.2"
        checkout main
        merge "develop" id: "New Feat" tag: "1.1.0"
        branch "hotfix"
        checkout "hotfix"
        commit id: "fix: JIRA-9999"
        checkout main
        merge "hotfix" id: "Hotfix" tag: "1.1.1"

2 - 🌐 Gitlab pages

🌐 Gitlab pages

Wymagania

• GitLab repository z plikami markdown zgodnymi z framweork gohugo i template docsy
• Dostęp do panelu zarządzania DNS

1. Przygotowanie repozytorium z dokumentacją

1. Zainicjalizuj projekt MkDocs (jeśli jeszcze nie istnieje):

   hugo new my-project
   cd my-project
   

2. Dodaj plik .gitlab-ci.yml do repozytorium:

   image: $CONTAINER_IMAGE_GOHUGO
   
   🚀 build gohugo project:
   stage: build
   script:
      - npm install
      - hugo
   artifacts:
      paths:
         - public
   rules:
      - when: on_success
   
   pages:
      stage: deploy
      dependencies:
         - 🚀 build gohugo project
      script:
         - echo "publish pages"
      pages: true
      rules: !reference [.rule:deploy:gohugo, rules]
      environment:
         name: Production
         url: https://$CI_PROJECT_NAMESPACE.gitlab.io/
   only:
      - main
   

3. Wypchnij zmiany do GitLaba:

   git add .
   git commit -m "Init hugo site"
   git push origin main
   

4. Po chwili strona powinna być dostępna pod adresem domyślnym:

   https://<nazwa-użytkownika>.gitlab.io/<nazwa-repozytorium>
   

2. Podłączenie subdomeny docs.rachuna-net.pl

1. Repozytorium → Settings → Pages → kliknij New Domain

   

2. Ustawienie domeny np. docs.rachuna-net.pl

3. GitLab wygeneruje dwa rekordy DNS:

   • ALIAS:

     docs.rachuna-net.pl.  ALIAS  pl.rachuna-net.gitlab.io.
     

   • TXT:

     _gitlab-pages-verification-code.docs.rachuna-net.pl.  TXT  gitlab-pages-verification-code=<wygenerowany_kod>
     

4. ustawienie rekordów do strefy DNS domeny.

5. GitLab automatycznie zweryfikuje rekordy i wygeneruje certyfikat SSL (Let’s Encrypt)

1. Wystaw swoją aplikacje na gitlab-pages ✅ https://docs-7c5e90.gitlab.io
2. W ustawieniach pages należy wybrać Deploy → page → new domain:

Po wypełnieniu formularza otrzymasz wpisy do rekordów DNS

   docs.rachuna-net.pl ALIAS pl.rachuna-net.gitlab.io.
   _gitlab-pages-verification-code.docs.rachuna-net.pl TXT gitlab-pages-verification-code=XYZ

3. Po chwili następuje aktualizacja domeny
4. Utworzenie Certyfikatu SSL z Let’s Encrypt

3. Podłączenie domeny głównej

Dla domen głównych nie można użyć ALIAS/CNAME, należy użyć rekordu A.

1. W ustawieniach Pages → New Domain → dodaj rachuna-net.pl

2. Skonfiguruj DNS:

   rachuna-net.pl.                                  A     35.185.44.232
   _gitlab-pages-verification-code.rachuna-net.pl.  TXT   gitlab-pages-verification-code=<kod>
   

3. Po propagacji DNS i weryfikacji – certyfikat SSL zostanie wystawiony automatycznie.

4. Efekt końcowy

Po wykonaniu powyższych kroków, strona MkDocs będzie dostępna pod Twoją własną domeną z certyfikatem SSL, np.:

https://docs.rachuna-net.pl

Przydatne linki

• hugo – Dokumentacja
• GitLab Pages – Custom Domains
• Let’s Encrypt

3 - Conventional Commits

Format wiadomości commitów

Wiadomość commita powinna być zgodna z poniższym schematem:

<typ>[!][(zakres)]: krótki opis zmiany

Przykłady

feat: dodano obsługę logowania
fix(auth): naprawiono błąd walidacji tokenu
refactor!: przebudowano system autoryzacji (breaking change)
chore(ci): aktualizacja pipeline’a GitLab CI

Typy commitów

Breaking changes

Aby oznaczyć zmianę łamiącą kompatybilność wsteczną, należy dodać wykrzyknik (!) po typie commita.

git commit -m 'refactor!: zmieniono sposób uwierzytelniania'

Korzyści ze stosowania

• ✅ Spójna i czytelna historia commitów
• ✅ Automatyczne generowanie changelogów
• ✅ Wsparcie dla semantic-release i automatycznego wersjonowania
• ✅ Łatwiejsze code review i analiza zmian
• ✅ Możliwość automatycznej walidacji commitów w CI/CD

Podsumowanie

Wdrożenie Conventional Commits to szybki krok w stronę lepszej automatyzacji, przejrzystości i jakości pracy w projektach GitLab. Rekomendujemy uwzględnienie tej konwencji w każdym nowym repozytorium oraz integrację z commitlint, semantic-release i husky.

regexp:

(build|chore|ci|docs|params|feat|fix|perf|refactor|style|test|revert|merge|release|hotfix|fixup|squash|wip|BREAKING CHANGE)(\\(.+\\))?: .+