Generator GitHub Actions matrix

Generator macierzy GitHub Actions — równoległe testy wielu środowisk

Generator macierzy GitHub Actions tworzy gotowy plik .github/workflows/ci.yml, który uruchamia ten sam zestaw testów dla wielu systemów oraz wersji PHP i Node. Wybierasz wymiary, wyjątki i dodatkowe kombinacje, a narzędzie składa poprawnie wcięty YAML z cache zależności, ograniczonymi uprawnieniami i kontrolą maksymalnej liczby zadań.

Po co używać strategii matrix

Pojedynczy zielony test na jednej wersji środowiska nie gwarantuje zgodności całego projektu. Biblioteka może działać na PHP 8.3, lecz zawieść na 8.2; aplikacja frontendowa może zachowywać się inaczej na Node 20 i 22; skrypt powłoki może przejść na Ubuntu, a nie zadziałać na Windows. Blok strategy.matrix opisuje te warianty raz, a GitHub rozwija je do osobnych jobów wykonywanych równolegle.

Iloczyn wymiarów i limit liczby jobów

Macierz jest iloczynem kartezjańskim list. Dwa systemy, dwie wersje PHP i trzy wersje Node dają 2 × 2 × 3 = 12 podstawowych jobów. Każdy zużywa minuty runnera i wykonuje instalację zależności, dlatego większa liczba nie zawsze oznacza lepsze CI. Generator liczy górną granicę jako iloczyn bazowy powiększony o wpisy include i odrzuca konfigurację przekraczającą limit 256 zadań GitHub Actions.

W praktyce zacznij od Ubuntu oraz wspieranych wersji runtime. Windows lub dodatkowe wydania dodawaj wtedy, gdy projekt rzeczywiście deklaruje taką zgodność. Pełną macierz warto uruchamiać dla pull requestów do głównej gałęzi, a kosztowne testy integracyjne można później przenieść do osobnego workflow.

Jak skonfigurować matrix, include i exclude

1. Wpisz nazwę workflow i gałęzie, dla których mają działać zdarzenia push oraz pull_request.
2. Podaj co najmniej jeden system runnera oraz jedną wersję PHP lub Node. Wartości oddzielaj przecinkami.
3. Jeśli konkretna kombinacja nie działa, dodaj w exclude wiersz w formacie os=windows-latest, php=8.2, node=20.
4. Jeśli potrzebujesz wariantu spoza list podstawowych, wpisz analogiczny zestaw w include. Używaj tylko aktywnych wymiarów.
5. Włącz cache, testy i lint zgodnie z plikami projektu, skopiuj wynik i zapisz go jako .github/workflows/ci.yml.
6. Przed commitem sprawdź plik w walidatorze YAML oraz dopasuj polecenia php artisan test, npm test i npm run lint.

Bezpieczne cytowanie wartości YAML

Nazwy gałęzi, runnerów i wersje trafiają do pliku jako cytowane skalary. Ma to znaczenie dla wartości zawierających dwukropek, znak #, słowa przypominające wartości logiczne lub numery wersji. Bez cytowania parser YAML mógłby potraktować fragment jako komentarz, liczbę albo nowy klucz. Generator odrzuca także znaki sterujące i nowe linie w polach jednoliniowych, więc dane formularza nie mogą dopisać obcej sekcji workflow.

Wcięcia są dwuspacjowe, a elementy include i exclude powstają jako listy map. Dzięki temu każda reguła zachowuje relację między wymiarami. Duplikaty wartości oraz identyczne reguły są usuwane przed wygenerowaniem wyniku.

Minimalne uprawnienia i kontrola kosztu

Workflow jawnie ustawia permissions: contents: read. Testy mogą odczytać kod pobrany przez checkout, ale nie otrzymują prawa zapisu do repozytorium, issues ani paczek. Job ma również timeout-minutes: 30, aby zawieszony test nie zużywał minut bez końca. Jeżeli później dodasz publikację wydania, wdrożenie lub komentarz do pull requesta, rozszerz uprawnienia tylko dla jobu, który rzeczywiście ich potrzebuje.

Wersje oficjalnych akcji i cache

Wynik używa aktualnych głównych wydań oficjalnych akcji: actions/checkout@v7, actions/setup-node@v7 oraz actions/cache@v6. Akcja społecznościowa shivammathur/setup-php pozostaje w linii @v2, ponieważ taki jest jej bieżący major. Przypięcie do majora pozwala otrzymywać poprawki zgodne z daną linią; w środowisku o podwyższonych wymaganiach bezpieczeństwa można ręcznie zastąpić major pełnym hashem commita.

Cache npm jest obsługiwany przez setup-node i kluczowany według package-lock.json. Cache pobrań Composera korzysta z actions/cache, systemu runnera, wersji PHP i hasha composer.lock. Gdy lockfile się zmieni, powstaje nowy klucz; prefiks restore pozwala wykorzystać najbliższy wcześniejszy wpis. Podobne zależności etapów można porównać z wynikiem generatora GitLab CI.

Co trzeba dopasować po wygenerowaniu

Narzędzie nie zna struktury konkretnego repozytorium. Polecenie php artisan test pasuje do Laravel, ale biblioteka może wymagać vendor/bin/phpunit albo vendor/bin/pest. Analogicznie npm test i npm run lint muszą istnieć w sekcji scripts pliku package.json. Jeśli projekt buduje kontener, przygotuj bazę przez generator Dockerfile; dla własnego serwera CI punktem odniesienia będzie generator Jenkinsfile.

Sprawdź również, czy wszystkie systemy potrafią wykonać użyte komendy. GitHub stosuje domyślnie inną powłokę na Windows niż na Linux. Komendy Composer, npm i PHP są przenośne, lecz ręcznie dodane skrypty Bash mogą wymagać jawnego shell: bash albo ograniczenia do runnera Ubuntu.

Najczęściej zadawane pytania