Ansible Playbook

Dokumentacja techniczna

Kompletny pipeline CI/CD dla projektów Ansible Playbook. Obsługuje walidację statyczną, instalację ról Galaxy, testy składni i dry-run oraz deployment na środowiska zdefiniowane w GitLab.

Użycie

W projekcie dodaj do .gitlab-ci.yml:

include:
  - project: pl.rachuna-net/flows/gitlab
    file: pipelines/ansible-playbook/.gitlab-ci.yml
    ref: main

variables:
  PROJECT_TYPE: ansible-playbook

Struktura projektu

Oczekiwana struktura repozytorium projektu:

twoj-projekt/
├── playbooks/
│   └── install.yml          # playbook (ANSIBLE_PLAYBOOK_NAME)
├── inventory/
│   └── hosts.yml            # inventory (ANSIBLE_INVENTORY_PATH)
└── requirements.yml         # role Galaxy (REQUIREMENTS_FILE_PATH)

Joby i stagi

Przepływ CI (branch != main)

.pre        → 🕵 Set Version
validate    → 🔍 Analyze Conventional Commits
            → 🕵 yamllint           (tylko gdy zmienił się *.yml/*.yaml)
            → 🐚 shellcheck         (tylko gdy zmienił się *.sh/*.sh.yml)
            → 🔍 ansible-lint
dependency  → 📦 dependency
tests       → 🧩 ansible-syntax     (needs: ansible-lint + dependency)
            → 🔍 ansible-check      (needs: ansible-syntax + ansible-lint + dependency)
publish     → 📍 Publish Version    (needs: Set Version + validate joby + ansible-check)

Przepływ CD (źródło: api/push/web)

.pre        → 🕵 Set Version
            → 🔧 Prepare Dynamic Deployment
dependency  → 📦 dependency
deployment  → 🚀 Trigger Deployment  → child pipeline:
                                          💥 Deployment:<ENV_NAME>  (per środowisko)
publish     → 📍 Publish Version

Tabela jobów

Job	Nazwa emoji	Stage	CI	CD
versioning (Set Version)	🕵 Set Version	.pre	✅	✅
environment-deployment-prepare	🔧 Prepare Dynamic Deployment	.pre	❌	✅
conventional-commits	🔍 Analyze Conventional Commits	validate	✅	❌
yamllint	🕵 yamllint	validate	✅*	❌
shellcheck	🐚 shellcheck	validate	✅*	❌
ansible-lint	🔍 ansible-lint	validate	✅	❌
dependency	📦 dependency	dependency	✅	✅**
build	🚀 build	build	❌	❌
ansible-syntax	🧩 ansible-syntax	tests	✅	❌
ansible-check	🔍 ansible-check	tests	✅	❌
unit-test	🧪 unit-test	tests	❌	❌
trigger-deployment	🚀 Trigger Deployment	deployment	❌	✅
deployment	💥 deployment	deployment	❌	✅**
publish	🌐 publish	publish	❌	❌
versioning (Publish Version)	📍 Publish Version	publish	✅	❌

* tylko gdy zmienił się odpowiedni typ pliku względem main ** uruchamia się w child pipeline (CI_PIPELINE_SOURCE == "parent_pipeline")

Ansible-specyficzne joby

🔍 ansible-lint (validate)

Statyczna analiza kodu Ansible. Uruchamia ansible-lint --force-color . na całym repozytorium.

📦 dependency (dependency)

Instaluje role Ansible Galaxy z pliku requirements.yml:

ansible-galaxy install -r "$REQUIREMENTS_FILE_PATH" -p playbooks/roles -f

Wynik zapisuje do cache (key: $CI_PROJECT_ID, policy: push → playbooks/roles/). Kolejne joby (ansible-syntax, ansible-check, deployment) pobierają role z cache (policy: pull).

🧩 ansible-syntax (tests)

Sprawdza składnię każdego playbooka w ANSIBLE_PLAYBOOKS_PATH:

ansible-playbook -i "$ANSIBLE_INVENTORY_PATH" --syntax-check "$playbook"

Opcjonalne argumenty: ANSIBLE_PLAYBOOK_EXTRA_ARGS.

🔍 ansible-check (tests)

Dry-run każdego playbooka (łączy się z hostami, nie wprowadza zmian):

ansible-playbook -i "$ANSIBLE_INVENTORY_PATH" --check "$playbook"

Wymaga SSH key (gitlab_ssh_key w before_script). Zależy od: ansible-syntax, ansible-lint, dependency.

💥 deployment (deployment — child pipeline)

Uruchamia check mode playbooka na konkretnym środowisku GitLab:

ansible-playbook \
  -i "$ANSIBLE_INVENTORY_PATH" \
  --check \
  "${ANSIBLE_PLAYBOOKS_PATH}/${ANSIBLE_PLAYBOOK_NAME}" \
  --limit "$CI_ENVIRONMENT_NAME"

Uruchamiany jako child pipeline triggerowany przez 🚀 Trigger Deployment (jeden job per środowisko z GitLab Environments).

Zmienne konfiguracyjne

Zmienne Ansible (wspólne dla syntax, check, deployment)

Zmienna	Domyślna	Opis
ANSIBLE_PLAYBOOKS_PATH	playbooks	Katalog z playbook’ami
ANSIBLE_PLAYBOOK_NAME	install.yml	Nazwa pliku playbooka (deployment)
ANSIBLE_INVENTORY_PATH	inventory/hosts.yml	Ścieżka do inventory
ANSIBLE_USER	root	Użytkownik SSH
ANSIBLE_HOST_KEY_CHECKING	false	Wyłączenie sprawdzania host key
ANSIBLE_FORCE_COLOR	true	Kolorowy output
VAULT_SKIP_VERIFY	"true"	Pominięcie weryfikacji Vault TLS
ANSIBLE_PLAYBOOK_EXTRA_ARGS	—	Dodatkowe argumenty ansible-playbook

Zmienne dependency

Zmienna	Domyślna	Opis
REQUIREMENTS_FILE_PATH	requirements.yml	Ścieżka do pliku requirements

Runner

Wszystkie joby uruchamiane na runnerze z tagiem gitlab-rnp.

Prefiks YAML

.pipelines.ansible-playbook.*