Gdzie ma być ten plik?

W **korzeniu repo**, nazwany dokładnie **`.gitlab-ci.yml`** (z kropką na początku). GitLab wyłapie automatycznie. Możesz też wskazać plik zewnętrzny w Project Settings -> CI/CD -> General pipelines, ale konwencja to plik w korzeniu repo, wersjonowany razem z kodem.

Jaka jest różnica między stages a needs?

**Stages** definiują twardą kolejność: każdy job w etapie 1 kończy się, zanim ruszy jakikolwiek w etapie 2. **needs** pozwala obejść tę kolejność: job z `needs: [setup]` startuje, gdy tylko skończy się `setup`, nawet jeśli inne joby z wcześniejszych etapów wciąż jadą. Używaj `needs` do **fan-out parallelism** w późnych etapach, gdzie niektóre ścieżki mogą ruszyć wcześniej niż twarda kolejność etapów by pozwoliła.

Czemu mój wpis „needs" nie przechodzi walidacji?

Dwa typowe powody. **Raz:** job zależny jest w **późniejszym etapie** niż ten job, co jest zabronione (możesz odnosić się tylko do jobów, które już ruszyły). Kreator to wyłapuje. **Dwa:** nazwa joba ma literówkę. Kreator używa chipów, więc nie da się pomylić, ale jeśli importujesz istniejący YAML, sprawdź każdy wpis `needs:` po znaku.

rules czy only/except, czego użyć?

**rules:** to nowoczesna składnia (od GitLab 12.3) i to ją GitLab rekomenduje. **only/except** wciąż działa, ale jest w trybie utrzymaniowym: nie dostaje nowych funkcji. Nowe projekty powinny używać tylko `rules:`. Ten kreator pisze `rules:`. Typowa reguła: `if: $CI_COMMIT_BRANCH == "main"` z `when: on_success`, żeby uruchamiać tylko na main po udanych poprzednich etapach.

Jaka jest różnica między artifacts a cache?

**[[Artefakty||pliki przekazywane do kolejnych etapów i pobieralne z UI GitLaba przez konfigurowalny czas]]** to **outputy**: produkowane przez job, przekazywane do kolejnych etapów, trzymane przez czas `expire_in` (domyślnie 30 dni), pobieralne z UI GitLaba. Stosuj dla outputów buildu, raportów testów, coverage. **[[Cache||pliki wielokrotnego użytku między pipelinami dla tej samej gałęzi, np. node_modules]]** to **przestrzeń robocza** reużywana między pipelinami, żeby było szybciej: `node_modules`, `.gradle`, `.npm`. Cache jest kluczowany (zwykle po gałęzi); artefakty są przekazywane przez zależność między jobami.

Jak działają zmienne CI?

Trzy poziomy. **Raz:** `variables:` na górze pliku to globalne, widoczne w każdym jobie. **Dwa:** `variables:` wewnątrz joba to lokalne dla niego. **Trzy:** prawdziwe sekrety (tokeny, hasła) idą do **Project Settings -> CI/CD -> Variables**, nigdy do pliku YAML. Protected variables są widoczne tylko jobom na chronionych gałęziach; masked są ukrywane w logach. Odnosisz się `$NAZWA` albo `${NAZWA}` w skryptach.

Do czego służy allow_failure?

**allow_failure: true** sprawia, że padający job pokazuje się jako ostrzeżenie, ale **nie blokuje reszty pipelinu**. Częste zastosowania: opcjonalne lintery i skanery bezpieczeństwa, które chcesz widzieć, ale nie blokować deploya, eksperymentalne joby wczesnej fazy projektu, joby zależne od zewnętrznych serwisów, które flakeują. W połączeniu z `when: manual` to dobry wzorzec dla „miękkich" manualnych jobów, które mogą, ale nie muszą się zdarzyć i nie powinny blokować.

Jak debugować padający pipeline lokalnie?

GitLab Runner umie uruchomić pojedynczy job lokalnie: `gitlab-runner exec docker ` z plikiem na dysku. Potrzebuje Dockera i zainstalowanego runnera, ale reprodukuje dokładne zachowanie bez palenia minut CI. Dla krótszego feedback loopa użyj **`only:` / `rules:`**, żeby zawęzić do tymczasowej gałęzi debug, pushuj do niej i iteruj. Zawsze usuwaj reguły debug przed mergem.

Czy mogę dołączyć zewnętrzne pliki?

Tak. Top-level `include:` ściąga YAML z innych plików albo z innych repo. Typowe wzorce: `include: local: '.gitlab/templates/test.yml'`, żeby podzielić długi pipeline na pliki, albo `include: project: 'group/templates' file: 'docker.yml'`, żeby używać centralnych szablonów pipeline w wielu projektach. Ten kreator nie emituje `include:` (każdy pipeline jest samodzielny), ale możesz to dodać ręcznie do wyniku.

Kreator GitLab CI YAML - darmowy

PresetyKliknij, żeby załadować przykładowy pipeline

Ustawienia globalne

Domyślny obrazUżywany przez każdy job, który nie nadpisuje własnym `image:`. Np. `node:20-alpine`, `python:3.12`

Etapy (jeden w linii)Kolejność ma znaczenie. Każdy job musi pasować do jednego z tych etapówZmienne globalne (KLUCZ=wartość)Widoczne w każdym jobie. Sekrety zostaw w Settings -> CI/CD -> Variables

Joby3 job(ów)

Podstawy joba

Nazwa jobaUnikalna w całym pliku. Używana w `needs:` i w pipeline UIEtapMusi być jednym z etapów z listy powyżej

Obraz (nadpisanie, opcjonalnie)Pomiń, żeby użyć domyślnegoZmienne joba (opcjonalnie)`KLUCZ=wartość`, po jednej w linii. Widoczne tylko w tym jobieneeds (zależności poza etapem)

Job startuje, gdy tylko skończą się wskazane joby. Nie może odnosić się do późniejszych etapów

allow_failure

Jeśli włączone, padnięcie nie blokuje pipelinu (tylko ostrzeżenie)

Skrypty

before_script (opcjonalnie)Komendy uruchamiane przed każdym wpisem ze script. Jedna komenda w liniiscriptKomendy joba. Jedna komenda w linii. Może używać zmiennych ze środowiska runnera

Artefakty i cache

Artefakty: ścieżki (jedna w linii)Pliki/foldery do zachowania. Przekazywane do kolejnych etapówArtefakty: expire_inCzas wygaśnięcia, np. `1 hour`, `1 week`, `1 month`

Cache: keyKlucz do współdzielenia cache między pipelinami. Standard: `${CI_COMMIT_REF_SLUG}`Cache: ścieżki (jedna w linii)Foldery do przechowywania między pipelinami, np. `node_modules/`, `.npm/`

Reguły (rules)

Warunki uruchomienia joba. Każda reguła = wyrażenie `if:` + decyzja `when:`

.gitlab-ci.yml

Zapisz w korzeniu repo i zacommituj

42 linii

default:
  image: node:20-alpine

stages:
  - install
  - test
  - deploy

variables:
  CI_NODE_OPTIONS: --max-old-space-size=4096

install:
  stage: install
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour
  cache:
    key: npm-${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/
      - node_modules/

unit-test:
  stage: test
  script:
    - npm test
  cache:
    key: npm-${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/
      - node_modules/

deploy:
  stage: deploy
  script:
    - npm run build
    - npm run deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Wskazówki

Sekrety (tokeny, hasła) zawsze idą do Project Settings -> CI/CD -> Variables, nigdy do pliku
Cache key z `${CI_COMMIT_REF_SLUG}` daje osobny cache per gałąź, co chroni przed zatruciem cache między PR
Jeśli pipeline jest powolny, sprawdź czy nie serializujesz przez `needs:`, gdy mógłbyś jechać równolegle

Co robi ten kreator

.gitlab-ci.yml leży w korzeniu Twojego repo na GitLabie i opisuje cały pipeline: uporządkowane etapy (install, test, deploy), poszczególne joby z komendami, co buforować, co publikować jako artefakty i kiedy konkretny job ma się uruchomić (tylko main? tylko tagi? tylko gdy plik się zmienił?). To jeden plik, bez osobnego UI, wersjonowany razem z kodem.

Ten kreator pisze ten plik za Ciebie. Wybierz preset (test + deploy, push do rejestru Dockera, GitLab Pages), edytuj etapy i joby w formularzach, a prawa kolumna pokaże dokładny YAML do wrzucenia do `.gitlab-ci.yml`. Walidator sprawdza typowe pułapki: job wymagający innego joba w późniejszym etapie, job odnoszący się do etapu, którego nie ma w `stages:`, zdublowane nazwy jobów, joby bez skryptu.

Wszystko działa w przeglądarce. Nic się nigdzie nie wysyła, nie potrzebujesz konta, żaden pipeline tu nie startuje. Wynikiem jest ten sam tekst, który napisałbyś ręcznie.

Jak używać

Wybierz preset u góry: Test + deploy, Push do rejestru Dockera, GitLab Pages. Formularz wypełni sensowne wartości.

Ustaw domyślny obraz (używany przez każdy job, który go nie nadpisuje), uporządkowaną listę etapów i ewentualne zmienne globalne w formacie `KLUCZ=wartość`.

Dodaj joby w zakładkach. Dla każdego: unikalna nazwa, etap (musi pasować do listy etapów), opcjonalne nadpisanie obrazu, opcjonalne zmienne i needs.

Wpisz skrypt (jedna komenda w linii). Opcjonalnie dodaj before_script dla wspólnych komend startowych.

Ustaw artefakty (ścieżki i `expire_in`) dla output buildu. Skonfiguruj cache z kluczem i ścieżkami, żeby przyspieszyć kolejne przebiegi.

Dodaj reguły z wyrażeniem `if:`, np. `$CI_COMMIT_BRANCH == "main"`. Wybierz `on_success`, `always`, `manual` (wymaga kliknięcia) albo `never`.

Włącz allow_failure dla jobów, które nie powinny blokować pipelinu, gdy padną (lintery, skanery bezpieczeństwa, które są tylko doradcze).

Kliknij Kopiuj w panelu podglądu albo Pobierz, żeby zapisać jako `.gitlab-ci.yml`. Potem zacommituj do korzenia repo. Kolejny push odpali pipeline.

Kiedy się przydaje

Siedem konkretnych sytuacji, w których kreator GitLab CI oszczędza realnie czas:

Pierwszy pipeline w nowym projekcie. Wybierasz „Test + deploy", zmieniasz komendę testów, commitujesz. Gotowe w dwie minuty zamiast przegryzania długich dokumentów GitLaba.
Dodanie pushu do rejestru Dockera do istniejącego pipelinu. Sekwencja login + tag + push to znany taniec; kreator pisze go za Ciebie, a Ty tylko wpisujesz nazwę obrazu.
Job deploy uruchamiany tylko na main. Składnia `rules:` z `if:` to nowoczesny sposób (zastępuje stare `only:` / `except:`), a literówki marnują pełny przebieg pipelinu.
Cache node_modules albo pip między pipelinami. Sekcja cache jest krótka, ale łatwo ją źle sformatować. Kreator domyślnie pisze działający cache z standardowym kluczem `$CI_COMMIT_REF_SLUG`.
Pipeline z kilkoma etapami i jobami równoległymi w teście. Kilka jobów w etapie `test` jedzie równolegle automatycznie. Kreator robi tę strukturę oczywistą, żebyś przypadkiem nie zserializował.
Ręczna bramka deployu. Ustawiasz regule deployu `when: manual` i tylko jawne kliknięcie w UI GitLaba uruchamia deploy. Częsty wzorzec dla produkcji.
Deploy strony GitLab Pages. Specjalny job `pages` musi publikować do `public/` jako artefakt. Preset „Pages deploy" zapisuje tę konwencję dokładnie.

Pytania i odpowiedzi

GitLab CI to wbudowany w GitLaba system CI/CD. Wrzucasz plik `.gitlab-ci.yml` do korzenia repo, GitLab wyłapuje go automatycznie i każdy push uruchamia pipeline. Każdy pipeline ma etapy (uporządkowane grupy: install, test, deploy), a każdy etap ma joby, które jadą równolegle na współdzielonych albo własnych runnerach. Darmowy plan zawiera runnery hostowane przez GitLab z miesięcznym limitem minut. Własne runnery są darmowe i bez limitu.

default: image: node:20-alpine stages: - install - test - deploy variables: CI_NODE_OPTIONS: --max-old-space-size=4096 install: stage: install script: - npm ci artifacts: paths: - node_modules/ expire_in: 1 hour cache: key: npm-${CI_COMMIT_REF_SLUG} paths: - .npm/ - node_modules/ unit-test: stage: test script: - npm test cache: key: npm-${CI_COMMIT_REF_SLUG} paths: - .npm/ - node_modules/ deploy: stage: deploy script: - npm run build - npm run deploy rules: - if: $CI_COMMIT_BRANCH == "main"