Workflow GitHub Actions może wyglądać poprawnie w edytorze YAML, a mimo to nie doprowadzić do wdrożenia. Czasem nie uruchamia się wcale, czasem zatrzymuje się na oczekiwaniu na akceptację, a innym razem przechodzi przez testy i budowanie, po czym kończy się błędem podczas publikacji obrazu lub logowania do chmury. Najszybsza diagnoza zaczyna się od ustalenia, na jakim etapie pipeline przestał działać: przed uruchomieniem workflow, w konkretnym jobie, przy przekazywaniu artefaktu czy dopiero podczas autoryzacji do środowiska docelowego. [2]
Najczęstsze pytania brzmią: dlaczego GitHub Actions nie uruchamia workflow po merge’u, czemu job jest pomijany, skąd bierze się błąd 403 albo permission denied, dlaczego sekret jest pusty i jak sprawdzić, czy blokadą nie jest wymagane zatwierdzenie środowiska. Odpowiedzi zwykle znajdują się w jednej z siedmiu grup błędów konfiguracyjnych.
Dlaczego workflow GitHub Actions zatrzymuje się przed wdrożeniem
Trzy różne objawy, trzy różne miejsca poszukiwań
Brak wdrożenia nie zawsze oznacza awarię skryptu deployującego. Jeśli workflow w ogóle nie pojawia się w zakładce Actions, problem występuje przed wykonaniem jakiegokolwiek kodu. Wtedy trzeba sprawdzić zdarzenie zdefiniowane w on, nazwę gałęzi, tag, filtr ścieżek oraz to, czy plik workflow znajdował się w odpowiedniej wersji repozytorium w chwili wystąpienia zdarzenia.
Drugi przypadek to workflow widoczny w historii, ale job oznaczony jako skipped, queued albo oczekujący na zatwierdzenie. Skipped zwykle wynika z warunku if, niespełnionej zależności needs lub filtra środowiska. Status queued może wskazywać na brak dostępnego runnera, etykietę niepasującą do żadnego wykonawcy albo limit równoległości. Oczekiwanie na akceptację najczęściej wiąże się z regułami ochrony środowiska.
Trzeci scenariusz jest najbardziej mylący: testy przechodzą, obraz zostaje zbudowany, lecz wdrożenie kończy się błędem. Wówczas konfiguracja uruchamiania może być prawidłowa, ale nie działa autoryzacja, sekret jest niedostępny, artefakt ma inną nazwę, a docelowa usługa odrzuca nieprawidłowy obraz lub manifest. Rozdzielenie tych etapów oszczędza czas, ponieważ logi kompilacji nie wyjaśnią błędu występującego przy federacji tożsamości w chmurze.
Jak czytać interfejs GitHub Actions
Diagnozę najlepiej prowadzić od ogółu do szczegółu. Najpierw sprawdź status całego workflow, potem status każdego joba, a następnie pierwszy krok, który zakończył się błędem. Późniejsze komunikaty mogą być jedynie konsekwencją wcześniejszego problemu. Jeżeli job budujący obraz zakończył się niepowodzeniem, błąd w jobie deployującym może brzmieć tylko „required job failed” i nie wskazywać prawdziwej przyczyny.
- Brak uruchomienia workflow oznacza konieczność sprawdzenia
on, gałęzi, tagów i ścieżek. skippedwymaga analizyif,needs, wyniku poprzedniego joba i kontekstu zdarzenia.queuedkieruje uwagę na runner, etykiety, limity i kolejkę.- Błąd w kroku wymaga czytania komunikatu oraz kilku linii poprzedzających go w logu.
- Oczekiwanie na akceptację wskazuje na reguły environment protection rules.
Przydatne jest również porównanie wartości kontekstu z oczekiwaniami. W logach nie należy wypisywać sekretów, ale można bezpiecznie sprawdzić nazwę gałęzi, rodzaj zdarzenia, wynik poprzedniego joba czy obecność opcjonalnej zmiennej za pomocą jawnego warunku. Jeśli problem dotyczy dostępu, komunikaty 401, 403, authentication failed, permission denied i resource not accessible by integration zwykle zawężają obszar poszukiwań.
1. Zbyt wąskie filtry on, które w ogóle nie uruchamiają wdrożenia
Workflow reaguje na inne zdarzenie niż to, które rzeczywiście następuje
Najbardziej podstawowy błąd konfiguracji GitHub Actions polega na pomyleniu zdarzenia uruchamiającego workflow z etapem procesu, który ma być obsługiwany. push uruchamia workflow po wypchnięciu zmian do wskazanej gałęzi lub po utworzeniu tagu. pull_request reaguje na operacje związane z pull requestem, ale nie jest tym samym co wdrożenie po merge’u. workflow_dispatch daje możliwość ręcznego uruchomienia, a workflow_call służy do wywoływania workflow wielokrotnego użytku z innego workflow.
Przykładowo testy mogą działać na pull requestach, natomiast wdrożenie produkcyjne powinno odbywać się dopiero po push do main. Jeśli jedyny workflow zawiera: [3]
on:
pull_request:
branches:
- mainto zamknięcie pull requesta przez merge nie musi uruchomić oczekiwanego wdrożenia. Zdarzenie związane z pull requestem opisuje zmianę w procesie przeglądu, a wdrożenie po scaleniu powinno zwykle nasłuchiwać na wypchnięcie nowego stanu do gałęzi docelowej.
name: Deploy production
on:
push:
branches:
- main
workflow_dispatch:Dodanie workflow_dispatch nie naprawia błędnego automatu, ale zapewnia kontrolowaną ścieżkę awaryjną. Jest szczególnie użyteczne, gdy trzeba ponowić wdrożenie tego samego commita bez tworzenia pustego commita. Ręczne uruchomienie nie powinno jednak zastępować poprawnych filtrów, bo ukrywa problem i zachęca do obchodzenia procesu.
Filtry gałęzi, tagów i ścieżek działają razem
W konfiguracji GitHub Actions filtry nie są niezależnymi przełącznikami, z których wystarczy spełnić jeden. Jeśli workflow ma jednocześnie filtr gałęzi i filtr paths, muszą być spełnione oba warunki. Przykładowa konfiguracja:
on:
push:
branches:
- main
paths:
- 'app/**'nie uruchomi się po zmianie w Dockerfile, katalogu infra/ ani pliku konfiguracyjnym poza app/. To częsta przyczyna sytuacji, w której zmiana kodu aplikacji uruchamia pipeline, a zmiana obrazu kontenera lub infrastruktury już nie.
Podobny problem występuje przy niespójnych nazwach gałęzi. Projekt może używać master, podczas gdy workflow nasłuchuje na main. Czasem nazwa jest prawidłowa w jednym repozytorium, ale błędna po przeniesieniu pliku do innego. Warto też zweryfikować wielkość liter i dokładny zapis tagów. Filtr tags nie zastępuje filtra branches, a workflow oczekujący na tag nie uruchomi się po zwykłym pushu do gałęzi.
| Konfiguracja | Typowa konsekwencja | Co sprawdzić |
|---|---|---|
push.branches | Brak uruchomienia po zmianie w innej gałęzi | Dokładną nazwę gałęzi i strategię merge |
push.tags | Workflow reaguje tylko na tagi | Format tagu i sposób jego tworzenia |
paths | Zmiany infrastruktury lub obrazu są pomijane | Listę plików wpływających na wdrożenie |
pull_request | Testy działają, ale merge nie wdraża aplikacji | Czy potrzebny jest dodatkowy trigger push |
Jak diagnozować filtr, którego nie widać w logach
Jeżeli workflow nie został uruchomiony, nie będzie logu kroku, który można przeanalizować. Sprawdź historię zakładki Actions, nazwę gałęzi, typ operacji oraz lokalizację pliku w .github/workflows/. Istotna jest także wersja pliku workflow obowiązująca dla danego zdarzenia. Zmiana konfiguracji na jednej gałęzi nie wpływa wstecz na zdarzenia, które zaszły na innej.
Przy filtrach paths-ignore łatwo odwrócić logikę. Jeśli wykluczysz katalog zawierający pliki wpływające na deployment, pipeline będzie milczał właśnie wtedy, kiedy powinien zareagować. Bezpieczniejszą praktyką jest utrzymywanie krótkiej, jawnej listy ścieżek dla testów oraz osobnej, dobrze udokumentowanej konfiguracji wdrożeniowej.
Rozdzielenie workflow testowego od wdrożeniowego upraszcza także uprawnienia. Testy mogą reagować na pull requesty i działać na kodzie proponowanym, natomiast deploy może być uruchamiany tylko po push do chronionej gałęzi lub po utworzeniu wersjonowanego tagu. Dzięki temu przypadkowe otwarcie pull requesta nie próbuje zmienić środowiska produkcyjnego. [1]
2. Brak właściwych uprawnień GITHUB_TOKEN lub niepoprawna autoryzacja do chmury
Uprawnienia GitHub API nie są tym samym co dostęp do chmury
Workflow może uruchomić się prawidłowo, wykonać checkout i przejść testy, ale zatrzymać się przy publikacji pakietu, odczycie artefaktu, utworzeniu wydania albo aktualizacji zasobu GitHub. Przyczyną bywa zakres wbudowanego tokena GITHUB_TOKEN. Osobną klasę problemów stanowi logowanie do AWS, Azure, Google Cloud, rejestru kontenerów lub serwera przez SSH. Te dwa mechanizmy są często mylone, ponieważ oba kończą się podobnym komunikatem o braku dostępu.
GITHUB_TOKEN autoryzuje operacje wobec GitHub. Nie daje sam z siebie uprawnień do konta AWS ani do prywatnego klastra Kubernetes. Z kolei poprawnie skonfigurowana tożsamość chmurowa nie pozwoli opublikować obrazu do GitHub Container Registry, jeśli workflow nie ma odpowiedniego zakresu packages.
Minimalne i jawne permissions
Zakresy uprawnień można określić na poziomie całego workflow albo pojedynczego joba. Ograniczenie uprawnień globalnie i rozszerzenie ich tylko tam, gdzie są potrzebne, ułatwia audyt. Przykład dla budowania i publikowania obrazu do GitHub Container Registry może wyglądać tak:
name: Build and publish
on:
push:
branches:
- main
permissions:
contents: read
jobs:
publish:
permissions:
contents: read
packages: write
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push image
run: |
docker build -t ghcr.io/example/app:${{ github.sha }} .
docker push ghcr.io/example/app:${{ github.sha }}Zakres contents: read pozwala pobrać kod, a packages: write umożliwia publikację pakietu. Jeśli workflow tworzy release, może potrzebować dodatkowych uprawnień. Jeśli komentuje pull request, istotne jest pull-requests: write. Gdy pobiera artefakty, trzeba sprawdzić zarówno mechanizm używanej akcji, jak i wymagane zakresy dla danego zasobu.
Ustawienie write-all może szybko „naprawić” błąd, ale jest słabym rozwiązaniem. Zwiększa zakres skutków przejęcia workflow, utrudnia analizę audytową i zaciera informację, które operacje są rzeczywiście potrzebne. Lepsza jest poprawka minimalna: rozszerz konkretny job o jeden wymagany zakres i sprawdź, czy błąd znika.
OIDC: token to dopiero część zaufania
Przy logowaniu do chmury przez OIDC workflow potrzebuje zwykle uprawnienia:
permissions:
contents: read
id-token: writeTo jednak nie wystarczy. Dostawca chmurowy musi ufać właściwemu issuerowi, czyli https://token.actions.githubusercontent.com, oraz akceptować odpowiednią wartość audience. Równie ważny jest warunek dotyczący podmiotu tokena (sub). Można go ograniczyć na przykład do konkretnego repozytorium, gałęzi albo środowiska.
jobs:
deploy:
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4
- name: Authenticate to cloud
uses: example/cloud-auth-action@v1
with:
workload_identity_provider: ${{ secrets.CLOUD_PROVIDER }}
service_account: deployer@example.iam
audience: https://iam.example.comTypowy błąd polega na tym, że polityka zaufania dopuszcza tokeny z innej gałęzi niż ta, na której działa wdrożenie. Inny przypadek to ograniczenie do środowiska production bez przypisania joba do tego środowiska. Wtedy token jest poprawnie wystawiany przez GitHub, ale chmura odrzuca go przed nadaniem roli.
Przy diagnozie porównaj trzy elementy: uprawnienie id-token: write, parametry przekazane do akcji logującej oraz warunki trust policy po stronie chmury. Nie zapisuj pełnego tokena w logach. Wystarczy sprawdzić, czy job działa z oczekiwanej gałęzi i środowiska oraz czy używa właściwego providera i odbiorcy tokena.
Błędy związane z uruchamianiem workflow i dostępem do zasobów
3. Sekret lub zmienna środowiskowa jest przypisana do innego zakresu
Sekret może istnieć w ustawieniach repozytorium, organizacji albo konkretnego środowiska. Samo odwołanie ${{ secrets.DEPLOY_KEY }} nie gwarantuje, że job otrzyma wartość. Jeśli sekret znajduje się w środowisku production, job musi mieć jawnie przypisane:
jobs:
deploy:
environment:
name: production
runs-on: ubuntu-latest
steps:
- name: Deploy
run: ./scripts/deploy.shBrak przypisania środowiska może dać pustą zmienną, a następnie niejasny błąd logowania. Podobnie działają sekrety organizacyjne ograniczone do wybranych repozytoriów. Warto sprawdzić także różnicę między sekretami a zwykłymi zmiennymi konfiguracyjnymi zdefiniowanymi w sekcji env.
Nie testuj obecności sekretu przez wypisywanie jego wartości. Bezpieczniejszy jest warunek, który sprawdza, czy zmienna nie jest pusta:
- name: Validate deployment configuration
env:
DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
run: |
test -n "$DEPLOY_HOST" || { echo "Brak DEPLOY_HOST"; exit 1; }
test -n "$DEPLOY_KEY" || { echo "Brak DEPLOY_KEY"; exit 1; }4. Zależności między jobami blokują wdrożenie
Job zdefiniowany przez needs nie uruchomi się, jeśli wymagany wcześniej job zakończy się błędem, zostanie pominięty albo nie spełni warunku if. W efekcie testy mogą wyglądać na zakończone, ale job wdrożeniowy pozostaje oznaczony jako skipped.
jobs:
test:
runs-on: ubuntu-latest
steps:
- run: ./scripts/test.sh
deploy:
needs: test
if: ${{ github.ref == 'refs/heads/main' }}
runs-on: ubuntu-latest
steps:
- run: ./scripts/deploy.shSprawdź osobno wynik każdego joba oraz warunki jego uruchomienia. Częstym błędem jest użycie needs.test.result == 'success' razem z dodatkowym warunkiem, który nigdy nie zachodzi, albo pomylenie github.ref z nazwą gałęzi dostępną w innym kontekście.
Jeżeli wdrożenie ma być dozwolone tylko po udanych testach, lepiej pozostawić zależność jawną i poprawić warunek niż usuwać needs. Usunięcie zależności może uruchomić deploy równolegle z testami, czyli pozornie rozwiązać problem kosztem bezpieczeństwa procesu.
5. Runner nie ma wymaganych narzędzi albo nie może dotrzeć do zasobu
Workflow może działać na poprawnej gałęzi, ale zatrzymać się dlatego, że runner nie ma programu, właściwej wersji klienta albo dostępu sieciowego do celu. Obraz ubuntu-latest nie oznacza, że zawiera każdy używany przez projekt CLI. Problemem bywa również prywatny endpoint dostępny wyłącznie z sieci firmowej.
- name: Check deployment tools
run: |
docker --version
kubectl version --client
terraform versionJeśli narzędzie nie jest preinstalowane, zainstaluj je jawnie za pomocą oficjalnej akcji lub kroku instalacyjnego. Gdy zasób znajduje się za firewallem, sam sekret nie rozwiąże problemu. Potrzebny może być self-hosted runner, połączenie VPN, allowlista adresów IP albo prywatny runner w tej samej sieci.
Warto odróżnić błąd DNS, timeout i odmowę autoryzacji. Could not resolve host wskazuje na rozwiązywanie nazwy, connection timed out na trasę lub firewall, a 403 na politykę dostępu po uzyskaniu połączenia.
6. Artefakt lub obraz jest publikowany pod inną nazwą niż ta używana przy wdrożeniu
Budowanie obrazu i jego wdrażanie często odbywa się w różnych jobach. Jeśli pierwszy job zapisuje tag zawierający SHA commita, a drugi próbuje pobrać tag latest, wdrożenie zakończy się błędem mimo poprawnego builda. Podobne rozjechanie może dotyczyć nazwy artefaktu, rejestru, projektu lub regionu.
env:
IMAGE_NAME: ghcr.io/example/app:${{ github.sha }}
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: docker build -t "$IMAGE_NAME" .
- run: docker push "$IMAGE_NAME"
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: ./scripts/deploy.sh "$IMAGE_NAME"Najlepiej wyznaczać nazwę obrazu w jednym miejscu i przekazywać ją dalej jako output joba albo wspólną zmienną. Nie składaj jej niezależnie w kilku skryptach, ponieważ drobna różnica w wielkości liter, porcie rejestru lub tagu jest trudna do zauważenia w interfejsie Actions.
7. Ochrona środowiska, concurrency albo warunek wdrożenia zatrzymuje poprawny job
Job może mieć poprawne uprawnienia i poprawny obraz, a mimo to nie rozpocząć pracy z powodu reguł środowiska. Wymagana akceptacja, niedostępna gałąź dopuszczona do wdrożenia albo ograniczenie liczby równoległych uruchomień często wygląda jak awaria pipeline’u.
concurrency:
group: production-deploy
cancel-in-progress: false
jobs:
deploy:
environment:
name: production
runs-on: ubuntu-latest
steps:
- run: ./scripts/deploy.shGrupa concurrency może pozostawić nowe uruchomienie w kolejce, gdy poprzednie wdrożenie nadal trwa. Przy cancel-in-progress: true nowszy run może z kolei anulować wcześniejszy, nawet jeśli ten był już blisko końca. Przed zmianą ustawienia sprawdź, czy projekt wymaga kolejkowania wdrożeń, czy raczej automatycznego zastępowania starszych uruchomień. [5]
Na końcu skontroluj warunki środowiska: dozwolone gałęzie, wymaganych recenzentów, sekrety środowiskowe oraz nazwę environmentu używaną w jobie. Najmniejsza różnica, na przykład prod zamiast production, może skierować workflow do innego zestawu reguł i zasobów. [4]
Krótka kontrola przed ponownym uruchomieniem
Po poprawieniu konfiguracji nie uruchamiaj od razu pełnego wdrożenia produkcyjnego. Najpierw sprawdź najważniejsze zależności w tej kolejności:
- czy workflow uruchamia się dla właściwego zdarzenia, gałęzi i ścieżki,
- czy job otrzymuje wymagane sekrety, zmienne i uprawnienia,
- czy runner ma narzędzia oraz dostęp sieciowy do celu,
- czy nazwa artefaktu lub obrazu jest identyczna podczas publikacji i wdrażania,
- czy środowisko, reguły akceptacji i mechanizm
concurrencypozwalają rozpocząć job.
Dobrym testem jest uruchomienie workflow na tym samym obrazie runnera i z możliwie zbliżonymi warunkami, ale z bezpiecznym środowiskiem docelowym. Dzięki temu można potwierdzić konfigurację bez ryzyka zmiany produkcji. Gdy awaria wystąpi ponownie, porównaj pierwszy nieudany krok z oczekiwanym etapem procesu, zamiast analizować cały plik YAML naraz.
Najczęściej zadawane pytania (FAQ)
Dlaczego workflow GitHub Actions nie uruchamia się po merge’u?
Sprawdź, czy workflow nasłuchuje na zdarzenie push do właściwej gałęzi. Sam trigger pull_request może uruchamiać testy, ale nie musi obsługiwać wdrożenia po scaleniu zmian.
Co oznacza status skipped w GitHub Actions?
Status skipped zwykle wynika z warunku if, niespełnionej zależności needs albo filtra środowiska. Warto sprawdzić także wynik poprzedniego joba i kontekst zdarzenia.
Dlaczego job GitHub Actions ma status queued?
Status queued może wskazywać na brak dostępnego runnera, niepasującą etykietę wykonawcy, kolejkę lub limit równoległości.
Czym różnią się uprawnienia GITHUB_TOKEN od dostępu do chmury?
GITHUB_TOKEN służy do autoryzacji operacji wobec GitHub. Nie zapewnia automatycznie dostępu do AWS, Azure, Google Cloud ani prywatnego klastra Kubernetes.
Jak sprawdzić, czy problemem jest ochrona środowiska?
Jeśli workflow oczekuje na akceptację, sprawdź reguły ochrony przypisane do środowiska. Taki status wskazuje na konieczność zatwierdzenia przed dalszym wykonaniem.
Najważniejsze wnioski
- Najpierw ustal, czy workflow nie uruchomił się, został pominięty, czeka w kolejce czy zakończył się błędem w konkretnym kroku.
- Po merge’u wdrożenie wymaga właściwego triggera, zwykle
pushdo docelowej gałęzi, a nie wyłączniepull_request. - Filtry gałęzi, tagów i ścieżek mogą wspólnie ograniczyć uruchamianie workflow bardziej, niż zakłada konfiguracja.
- Uprawnienia
GITHUB_TOKENtrzeba rozpatrywać osobno od autoryzacji do chmury i rejestru obrazów. - Najskuteczniejsza diagnoza zaczyna się od pierwszego błędnego kroku, a nie od końcowego komunikatu zależnego joba.

