Przejdź do treści
Wiedza • Bezpieczeństwo • Technologia
KOŃSKA
GÓRKA

AI • CYBERBEZPIECZEŃSTWO • IT

DevOps i CICD

7 błędów w konfiguracji GitHub Actions, które blokują wdrożenia

7 błędów w konfiguracji GitHub Actions, które blokują wdrożenia
Rate this post

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.
  • skipped wymaga analizy if, needs, wyniku poprzedniego joba i kontekstu zdarzenia.
  • queued kieruje 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:
      - main

to 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.

KonfiguracjaTypowa konsekwencjaCo sprawdzić
push.branchesBrak uruchomienia po zmianie w innej gałęziDokładną nazwę gałęzi i strategię merge
push.tagsWorkflow reaguje tylko na tagiFormat tagu i sposób jego tworzenia
pathsZmiany infrastruktury lub obrazu są pomijaneListę plików wpływających na wdrożenie
pull_requestTesty działają, ale merge nie wdraża aplikacjiCzy 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: write

To 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.com

Typowy 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.sh

Brak 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.sh

Sprawdź 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 version

Jeś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.sh

Grupa 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 concurrency pozwalają 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 push do docelowej gałęzi, a nie wyłącznie pull_request.
  • Filtry gałęzi, tagów i ścieżek mogą wspólnie ograniczyć uruchamianie workflow bardziej, niż zakłada konfiguracja.
  • Uprawnienia GITHUB_TOKEN trzeba 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.

Źródła

AutorMarta Witkowski

Marta Witkowski zajmuje się wdrażaniem rozwiązań opartych na sztucznej inteligencji w działach operacyjnych i obsługi klienta. Pracowała przy projektach chatbotów, systemów rekomendacyjnych oraz analityki predykcyjnej, pomagając firmom przełożyć dane na konkretne decyzje. W artykułach pokazuje, jak krok po kroku planować projekty AI: od doboru danych, przez wybór narzędzi, po mierzenie efektów. Każde rozwiązanie weryfikuje na podstawie pilotaży i testów A/B, korzystając z dokumentacji, repozytoriów modeli i publikacji branżowych. Stawia na transparentność algorytmów i odpowiedzialne podejście do prywatności użytkowników.