Rozdział 3: Workflow CI — bramki jakości
Czas na pierwszy automat. W tym rozdziale dodajemy CI — plik, który przy każdym git push i każdym Pull Requeście uruchamia Twoje testy i analizę kodu na maszynach GitHuba. To czynność 🔁 jednorazowa (piszesz plik raz), konfigurowana 🐙 w repo.
Po tym rozdziale w zakładce Actions na GitHubie zobaczysz zielony (lub czerwony) wynik „CI" po każdym push.
Co to jest workflow i gdzie mieszka
Workflow to plik YAML w katalogu .github/workflows/. GitHub automatycznie go wykrywa i uruchamia na swoich maszynach (nazywanych runnerami). Jeden plik = jeden automat.
Nasz plik CI: .github/workflows/ci.yml.
YAML to prosty format tekstowy oparty na wcięciach. Uwaga: wcięcia robimy spacjami, nigdy tabulatorami — inaczej plik jest niepoprawny.
Zasada: CI = to samo co lokalne bramki jakości 🧩
Najlepszy CI robi dokładnie to, co robisz lokalnie przed commitem. W FactoryCode bramki jakości uruchamia make check:
make check = phpstan + php-cs-fixer + typecheck + testy
CI ma je powtórzyć na „czystej" maszynie GitHuba. Dzięki temu łapie błędy, które u Ciebie „działały", bo miałeś coś doinstalowanego lokalnie.
🎯 Specyficzne dla projektu: konkretne komendy (
phpstan,php-cs-fixer,phpunit,yarn typecheck) i usługi (PostgreSQL) zależą od stacku. W innym projekcie podmienisz je na swoje bramki. 🧩 Uniwersalna jest sama idea i szkielet pliku.
Plik ci.yml (FactoryCode) — w całości
Utwórz .github/workflows/ci.yml o treści:
name: CI
# Push na main + każdy Pull Request -> te same bramki co lokalnie.
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
backend:
name: Backend (PHP 8.4)
runs-on: ubuntu-latest
# PostgreSQL 16 jako serwis pomocniczy (tak jak kontener `database` w compose)
services:
database:
image: postgres:16-alpine
env:
POSTGRES_USER: app
POSTGRES_PASSWORD: '!ChangeMe!'
POSTGRES_DB: app
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U app"
--health-interval 10s
--health-timeout 5s
--health-retries 5
env:
DATABASE_URL: "postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8"
PHP_CS_FIXER_IGNORE_ENV: 1
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.4'
extensions: pdo_pgsql, intl, zip, mbstring
coverage: none
tools: composer:v2
- name: Cache Composer
uses: actions/cache@v4
with:
path: ~/.composer/cache
key: composer-${{ hashFiles('composer.lock') }}
restore-keys: composer-
- name: Install PHP dependencies
run: composer install --no-interaction --no-progress --prefer-dist --no-scripts
- name: Prepare databases (dev + test)
run: |
php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console doctrine:database:create --env=test --if-not-exists
php bin/console doctrine:migrations:migrate --env=test --no-interaction
- name: Warm up cache
run: php bin/console cache:clear
- name: PHPStan
run: php vendor/bin/phpstan analyse --memory-limit=256M
- name: PHP-CS-Fixer (dry-run)
run: php vendor/bin/php-cs-fixer fix --dry-run --diff --ansi
- name: PHPUnit
env:
APP_ENV: test
run: php bin/phpunit --testdox
frontend:
name: Frontend (TypeScript)
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
cache: yarn
- name: Install JS dependencies
run: yarn install --frozen-lockfile
- name: Type-check
run: yarn typecheck
- name: Build assets
run: yarn build
Co znaczy każda sekcja
| Sekcja | Znaczenie |
|---|---|
name: |
nazwa workflow widoczna w zakładce Actions |
on: |
kiedy uruchamiać — tu: push i PR na main |
jobs: |
zadania; u nas dwa równoległe: backend i frontend |
runs-on: |
typ maszyny GitHuba (ubuntu-latest) |
services: |
kontenery pomocnicze; tu PostgreSQL 16, bo testy potrzebują bazy |
env: |
zmienne środowiskowe dla joba (DATABASE_URL wskazuje na serwis bazy) |
steps: → uses: |
gotowe „klocki" z Marketplace (checkout, setup-php, setup-node, cache) |
steps: → run: |
Twoje komendy (composer, phpstan, phpunit, yarn) |
Dlaczego dwa joby? Backend (PHP) i frontend (TypeScript) są niezależne, więc uruchamiają się równolegle — szybciej.
⚠️ Kluczowa pułapka: kolejność kroków w backendzie
To najważniejszy, nieoczywisty fragment — zależny od tego, że FactoryCode ładuje tłumaczenia z bazy danych. Każde „rozgrzanie cache" (cache:clear) odpytuje tabelę trans_key. Jeśli baza jeszcze nie istnieje, CI się wywala.
Dlatego kolejność jest sztywna:
composer install --no-scripts ← pomija przedwczesny cache:clear
→ utwórz i zmigruj bazę dev (app)
→ utwórz i zmigruj bazę test (app_test)
→ cache:clear ← dopiero teraz (baza już jest)
→ phpstan
→ php-cs-fixer --dry-run
→ phpunit
Dwa szczegóły, które z tego wynikają:
composer installdajemy z flagą--no-scripts, żeby pominąć automatycznycache:clearna jeszcze pustej bazie (inaczej błądrelation "trans_key" does not exist).- Baza testowa nazywa się
app_test(sufiks_testdokłada konfiguracja Doctrine), dlatego tworzymy ją osobno komendą z--env=test.
🧩➡️🎯 Dla nowego projektu: ta pułapka jest specyficzna dla projektów, które w czasie rozgrzewki cache sięgają do bazy. Jeśli Twój projekt tego nie robi, kolejność może być prostsza. Zasada uniwersalna: jeśli jakikolwiek krok CI potrzebuje bazy, utwórz i zmigruj ją wcześniej.
Dodatkowo PHP_CS_FIXER_IGNORE_ENV: 1 wyłącza blokadę php-cs-fixera na najnowszym PHP (kosmetyka, ale bez tego bywa błąd).
Uruchomienie i weryfikacja 🐙
Co robisz: commitujesz plik i wysyłasz na GitHub.
# 💻 lokalnie
git add .github/workflows/ci.yml
git commit -m "ci: add GitHub Actions workflow"
git push origin main
Jak sprawdzić rezultat:
- Wejdź na
https://github.com/<REPO>/actions. - Zobaczysz przebieg „CI" z dwoma jobami (
backend,frontend). - ✅ zielony = wszystkie bramki przeszły. ❌ czerwony = kliknij w czerwony krok, by zobaczyć log błędu.
Oczekiwany rezultat: oba joby na zielono.
Częste problemy
| Objaw | Przyczyna | Rozwiązanie |
|---|---|---|
relation "trans_key" does not exist, exit code 7 |
cache rozgrzewany przed utworzeniem bazy | zachowaj kolejność: najpierw migracje, potem cache:clear; composer install --no-scripts |
| „The POSTGRES… / connection refused" w testach | zła nazwa hosta bazy | w CI baza jest pod 127.0.0.1:5432, nie database (to nazwa z Dockera) |
| php-cs-fixer przerywa z błędem o wersji PHP | brak flagi ignorującej env | dodaj PHP_CS_FIXER_IGNORE_ENV: 1 |
| żółte ostrzeżenia „Node.js 20 is deprecated" | starsze wersje akcji | to tylko ostrzeżenia, nie powodują czerwonego buildu; opcjonalnie podbij akcje do nowszej wersji |
Podsumowanie
- ✅ Masz plik
.github/workflows/ci.yml, który testuje kod przy każdym push/PR. - ✅ Rozumiesz sekcje
on,jobs,services,stepsoraz rolę usługi PostgreSQL. - ✅ Znasz kluczową pułapkę: baza musi istnieć przed rozgrzewką cache.
- ✅ Wiesz, co jest 🧩 uniwersalne (szkielet), a co 🎯 specyficzne (komendy bramek).
CI chroni jakość kodu. Teraz zbudujemy miejsce, do którego będziemy wdrażać — serwer VPS.
Dalej: Rozdział 4: Serwer VPS — zakup i konfiguracja.