Tworzenie niestandardowej akcji usługi GitHub

Zakończone

Funkcja GitHub Actions to zaawansowana funkcja, która ułatwia przechodzenie z kodu do chmury — od komfortu i wygody własnego repozytorium. W tym miejscu poznasz różne typy akcji usługi GitHub oraz metadanych, składni i poleceń przepływu pracy w celu utworzenia niestandardowych akcji usługi GitHub.

Typy akcji usługi GitHub

Akcje to poszczególne zadania, których można użyć do dostosowywania przepływów pracy programowania. Możesz utworzyć własne akcje, pisząc niestandardowy kod, który współdziała z repozytorium w celu wykonywania zadań niestandardowych lub za pomocą akcji udziałów społeczności usługi GitHub. Przechodząc przez różne akcje, zauważysz, że istnieją trzy różne typy akcji: akcje kontenera platformy Docker, akcje języka JavaScript i złożone akcje uruchamiania. Przyjrzyjmy się bliżej każdemu typowi akcji.

Akcje kontenera platformy Docker

Kontenery platformy Docker pakują środowisko przy użyciu kodu funkcji GitHub Actions. Oznacza to, że akcja jest uruchamiana w spójnym i niezawodnym środowisku, ponieważ wszystkie jego zależności znajdują się w tym kontenerze. Jeśli akcja musi zostać uruchomiona w określonej konfiguracji środowiska, kontenery platformy Docker są dobrym sposobem na przejście, ponieważ można dostosować system operacyjny i narzędzia. Wadą jest to, że ponieważ zadanie musi kompilować i pobierać kontener, akcje kontenera platformy Docker są często wolniejsze niż akcje języka JavaScript.

Przed utworzeniem akcji kontenera platformy Docker należy mieć podstawową wiedzę na temat używania zmiennych środowiskowych i systemu plików kontenera platformy Docker. Kroki, które należy wykonać w celu utworzenia akcji kontenera platformy Docker, są wtedy minimalne i proste:

1. Utwórz element , Dockerfile aby zdefiniować polecenia w celu złożenia obrazu platformy Docker.
2. action.yml Utwórz plik metadanych, aby zdefiniować dane wejściowe i wyjściowe akcji. runs: using: Ustaw wartość na docker , a runs: image: wartość na Dockerfile w pliku .
3. Utwórz plik w entrypoint.sh celu opisania obrazu platformy Docker.
4. Zatwierdź i wypchnij akcję do usługi GitHub przy użyciu następujących plików: action.yml, entrypoint.sh, Dockerfilei README.md.

Akcje języka JavaScript

Akcje języka JavaScript można uruchamiać bezpośrednio na maszynie modułu uruchamiającego i oddzielić kod akcji od środowiska używanego do uruchamiania akcji. Z tego powodu kod akcji jest uproszczony i może być wykonywany szybciej niż akcje w kontenerze platformy Docker.

W ramach wymagań wstępnych dotyczących tworzenia i używania spakowanych akcji Języka JavaScript należy pobrać Node.js, które obejmują narzędzie npm. Opcjonalnie (ale zalecanym krokiem jest użycie zestawu narzędzi GitHub Actions Toolkit Node.js, czyli kolekcji pakietów Node.js, które umożliwiają szybkie tworzenie akcji języka JavaScript z większą spójnością.

Kroki tworzenia akcji języka JavaScript są minimalne i proste:

1. action.yml Utwórz plik metadanych, aby zdefiniować dane wejściowe i wyjściowe akcji, a także poinformować moduł uruchamiający akcję, jak rozpocząć uruchamianie tej akcji w języku JavaScript.
2. index.js Utwórz plik z informacjami kontekstowymi o pakietach zestawu narzędzi, routingu i innych funkcjach akcji.
3. Zatwierdź i wypchnij akcję do usługi GitHub przy użyciu następujących plików: action.yml, , index.jsnode_modules, package.json, , package-lock.jsoni README.md.

Akcje złożonych kroków uruchamiania

Złożone akcje kroków uruchamiania umożliwiają ponowne użycie akcji przy użyciu skryptów powłoki. W ramach tej samej akcji można nawet mieszać wiele języków powłoki. Jeśli masz wiele skryptów powłoki do automatyzacji kilku zadań, możesz teraz łatwo przekształcić je w akcję i użyć ich ponownie dla różnych przepływów pracy. Czasami łatwiej jest napisać skrypt powłoki niż za pomocą języka JavaScript lub opakowującego kod w kontenerze platformy Docker.

Pakietowa akcja złożona

Spakowane akcje złożone łączą wiele kroków w jednostkę wielokrotnego użytku. Te akcje są definiowane w repozytorium i mogą być przywołyne w przepływach pracy w różnych repozytoriach. Pakowanie akcji złożonej upraszcza przepływy pracy, zmniejsza duplikację i zwiększa łatwość konserwacji.

Podczas tworzenia spakowanej akcji złożonej kroki są definiowane w jednym action.yml pliku. Ten plik określa dane wejściowe, dane wyjściowe oraz sekwencję poleceń lub akcji do wykonania. Spakowane akcje złożone są szczególnie przydatne do automatyzowania powtarzających się zadań lub łączenia wielu poleceń powłoki w jedną akcję wielokrotnego użytku.

Tworzenie złożonego qction

1. Konfigurowanie katalogu dla akcji złożonej

Akcja złożona musi być umieszczona we własnym katalogu, który znajduje się wewnątrz repozytorium.

Przykładowa struktura katalogów:

.github/actions/my-composite-action/
├── action.yml
└── scripts/
    └── my-script.sh

2. Zdefiniuj action.yml plik

W katalogu my-composite-action utwórz action.yml plik.

name: "My Composite Action"
description: "A reusable composite action that checks out code and sets up Node.js"

inputs:
  node-version:
    description: "The Node.js version to use"
    required: true

runs:
  using: "composite"
  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

Uwaga: Pole "composite" wskazuje, że ta akcja jest akcją złożoną.

3. Używanie akcji złożonej w przepływie pracy

Po utworzeniu akcji złożonej można odwoływać się do niej w przepływie pracy funkcji GitHub Actions.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Use my composite action
        uses: ./.github/actions/my-composite-action
        with:
          node-version: '18'

Jeśli akcja złożona jest udostępniana z innego repozytorium, odwołaj się do niego w następujący sposób:

uses: owner/repository/.github/actions/my-composite-action@v1

Dodawanie danych wyjściowych do akcji złożonej

Akcje złożone mogą definiować dane wyjściowe, których przepływy pracy mogą używać do przekazywania danych między krokami lub zadaniami. Dane wyjściowe są szczególnie przydatne do udostępniania wyników lub obliczonych wartości z jednej akcji do innej.

W poniższym przykładzie pokazano, jak zdefiniować i użyć danych wyjściowych w akcji złożonej:

Definiowanie danych wyjściowych w action.yml

Plik action.yml określa dane wyjściowe o nazwie script-result. Ta wartość jest pobierana z danych wyjściowych result kroku run-script. Krok run-script uruchamia polecenie powłoki Bash, aby ustawić wartość wyjściową.

outputs:
  script-result:
    description: "Result from the script"
    value: ${{ steps.run-script.outputs.result }}

runs:
  using: "composite"
  steps:
    - id: run-script
      run: echo "result=Success" >> $GITHUB_OUTPUT
      shell: bash

Używanie danych wyjściowych w przepływie pracy

Po utworzeniu akcji złożonej jej dane wyjściowe będą dostępne w przepływie pracy. Oto przykład:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run composite action
        id: my-action
        uses: ./.github/actions/my-composite-action

      - name: Display result
        run: echo "Script Result: ${{ steps.my-action.outputs.script-result }}"

W tym przykładzie:

• Akcja złożona jest wywoływana przy użyciu słowa kluczowego uses .
• Uzyskaj dostęp do danych wyjściowych script-result przy steps.<step-id>.outputs.<output-name> użyciu składni .
• Wyświetl wynik w dziennikach przepływu pracy.

Zdefiniuj dane wyjściowe w akcjach złożonych w celu utworzenia przepływów pracy wielokrotnego użytku i modułowych. Takie podejście upraszcza udostępnianie danych i zwiększa łatwość utrzymania.

Najlepsze rozwiązania dotyczące akcji złożonych

Najlepsze rozwiązanie	Opis
Wykorzystaj wersjonowanie	Użyj tagu v1 , aby odwołać się do stabilnej wersji 1.
Zachowaj modułowe akcje	Grupuj powiązane kroki wewnątrz akcji złożonej.
Dane wejściowe i wyjściowe dokumentu	Dodaj opisy dla danych wejściowych/wyjściowych w pliku action.yml.
Testowanie przed opublikowaniem	Zweryfikuj akcję złożoną w repozytorium testowym.

Akcja złożona w przepływie pracy

Akcje złożone to zaawansowany sposób upraszczania przepływów pracy przez łączenie wielu kroków w jednostkę wielokrotnego użytku. Te akcje umożliwiają zdefiniowanie sekwencji poleceń lub akcji w jednym action.yml pliku, co ułatwia konserwację i ponowne używanie logiki między przepływami pracy.

Zalety akcji złożonych:

• Możliwość ponownego użycia — zdefiniuj akcje raz i użyj ich w wielu przepływach pracy.
• Łatwość konserwacji — zmniejszanie duplikacji przez scentralizowanie logiki w ramach jednej akcji.
• Modułowość — łączenie wielu poleceń powłoki lub innych akcji w jedną jednostkę.

Opracowanie akcji do konfigurowania CLI na węzłach wykonawczych GitHub Actions

Wiele przepływów pracy CI/CD wymaga określonej wersji narzędzia CLI do interakcji z usługami w chmurze, zarządzania infrastrukturą lub wykonywania skryptów. Chociaż moduły uruchamiane w usłudze GitHub są wstępnie zainstalowane z wieloma narzędziami, mogą nie zawierać dokładnej wersji wymaganej przez przepływ pracy, zwłaszcza jeśli jest to starsza lub nieobsługiwana wersja. Zamiast instalować wymaganą wersję interfejsu wiersza polecenia w każdym przepływie pracy, możesz utworzyć akcję usługi GitHub wielokrotnego użytku , która:

• Zapewnia spójną instalację wymaganej wersji interfejsu wiersza polecenia między zadaniami.
• Upraszcza przepływy pracy przez scentralizowanie logiki instalacji.
• Optymalizuje buforowanie pod kątem szybszego wykonywania przepływu pracy.

Jak opracować akcję konfiguracyjną CLI

Akcja konfiguracji interfejsu wiersza polecenia to akcja oparta na języku JavaScript, która instaluje i konfiguruje interfejs wiersza polecenia w module uruchamiającym usługę GitHub.

Kroki tworzenia akcji:

Krok 1. Konfigurowanie katalogu akcji

Aby ręcznie utworzyć katalog dla akcji konfiguracji interfejsu wiersza polecenia, wykonaj następujące kroki:

1. Przejdź do repozytorium

2. Tworzenie nowego katalogu dla akcji
   Utwórz nowy katalog o nazwie my-cli-action wewnątrz .github/actions folderu. Dzięki temu akcja jest zorganizowana i jest zgodna z zalecaną strukturą usługi GitHub dla akcji niestandardowych.

3. Przejdź do nowego katalogu
   Przejdź do nowo utworzonego katalogu, aby rozpocząć dodawanie plików dla akcji:

4. Weryfikowanie struktury katalogów
   Po utworzeniu katalogu struktura repozytorium powinna wyglądać następująco:

your-repository/
├── .github/
│   ├── actions/
│   │   ├── my-cli-action/

Teraz możesz przystąpić do tworzenia pliku action.yml i innych niezbędnych plików dla akcji konfiguracyjnej interfejsu wiersza polecenia.

Krok 2. Definiowanie pliku metadanych action.yml

Utwórz plik action.yml, aby opisać akcję.

name: "Setup MyCLI"
description: "Installs MyCLI and adds it to the PATH"
author: "Your Name"

inputs:
  version:
    description: "The CLI version to install"
    required: false
    default: "latest"

runs:
  using: "node16"
  main: "index.js"

Dlaczego warto używać: node16? Ta akcja uruchamia kod JavaScript przy użyciu Node.js 16.

Krok 3. Tworzenie skryptu języka JavaScript w celu zainstalowania interfejsu wiersza polecenia

W tym samym katalogu utwórz plik o nazwie index.js i dodaj następujący kod:

const core = require('@actions/core');
const { execSync } = require('child_process');

async function run() {
  try {
    const version = core.getInput('version') || 'latest';
    
    console.log(`Installing MyCLI version: ${version}...`);

    execSync(`curl -fsSL https://cli.example.com/install.sh | sh`, { stdio: 'inherit' });

    console.log("MyCLI installed successfully.");
  } catch (error) {
    core.setFailed(`Installation failed: ${error.message}`);
  }
}

run();

Kod JavaScript powyżej używa metody core.getInput(), aby pobrać wersję interfejsu wiersza polecenia (CLI) określoną jako dane wejściowe. Następnie wykonuje polecenie curl, aby pobrać i zainstalować CLI. Jeśli proces instalacji zakończy się niepowodzeniem, akcja używa metody core.setFailed(), aby oznaczyć przepływ pracy jako niepowodzenie.

Krok 4. Testowanie akcji lokalnie

Przed użyciem akcji w przepływie pracy, przetestuj ją na GitHub-hostowanym runnerze.
Utwórz plik przepływu pracy (.github/workflows/test.yml) w repozytorium:

name: Test MyCLI Setup

on:
  push:
    branches:
      - main
      - feature/*

1. Wyzwalanie przepływu pracy
Przepływ pracy jest wyzwalany przy wypychaniach do gałęzi głównej i dowolnej gałęzi zgodnej ze wzorcem funkcji/* . Można to dostosować do strategii rozgałęziania repozytorium.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

2. Sklonuj repozytorium
Akcja actions/checkout@v4 służy do klonowania repozytorium na moduł uruchamiający. Dzięki temu przepływ pracy ma dostęp do plików repozytorium.

      - name: Install MyCLI
        uses: ./.github/actions/my-cli-action
        with:
          version: '1.2.3'

3. Uruchamianie akcji niestandardowej
Użycia ./.github/actions/my-cli-action odnoszą się do lokalnej akcji niestandardowej. Upewnij się, że katalog akcji i plik action.yml są poprawnie skonfigurowane. Dane wejściowe wersji określają wersję interfejsu wiersza polecenia do zainstalowania — w tym przypadku wersja 1.2.3.

      - name: Verify CLI Installation
        run: |
          echo "Checking MyCLI version..."
          mycli --version

4. Sprawdź instalację interfejsu wiersza polecenia
Ten krok uruchamia polecenie powłoki, by potwierdzić, czy CLI został zainstalowany pomyślnie. Sprawdza wersję zainstalowanego interfejsu wiersza poleceń, uruchamiając mycli --version.

Testowanie lokalne

Aby przetestować ten przepływ pracy lokalnie, użyj narzędzia CLI act.

act -j test

Symuluje to środowisko funkcji GitHub Actions na komputerze lokalnym, co umożliwia debugowanie i weryfikowanie przepływu pracy przed wypchnięciem zmian.

Porada dotycząca optymalizacji: buforowanie

Aby zwiększyć wydajność przepływu pracy, zbuforuj katalog instalacyjny interfejsu wiersza poleceń przy użyciu akcji actions/cache.

      - name: Cache MyCLI
        uses: actions/cache@v4
        with:
          path: ~/.mycli
          key: mycli-${{ runner.os }}-${{ inputs.version }}

Dzięki temu kolejne uruchomienia ponownie wykorzystują zbuforowaną instalację interfejsu wiersza polecenia, co skraca czas konfiguracji.

Najlepsze praktyki dotyczące czynności konfiguracji interfejsu wiersza polecenia

Najlepsze rozwiązanie	Opis
Wykorzystaj wersjonowanie	Zezwalaj użytkownikom na określanie wersji interfejsu wiersza polecenia za pomocą polecenia inputs.version.
Poprawnie obsłuż błędy	Użyj polecenia core.setFailed() , aby zakończyć działanie po błędach.
Instalacja CLI pamięci podręcznej	Zoptymalizuj wydajność przepływu pracy przy użyciu polecenia actions/cache.
Podaj dokumentację	Wyjaśnij użycie i dane wejściowe w README.md.

Rozwiązywanie problemów z akcjami języka JavaScript

Podczas pracy z akcjami GitHub opartymi na JavaScript mogą wystąpić nieoczekiwane zachowania, błędy lub niepowodzenia podczas wykonywania przepływu pracy. Ta lekcja zawiera techniki i narzędzia ułatwiające identyfikowanie i rozwiązywanie problemów w akcjach języka JavaScript.

Typowe scenariusze rozwiązywania problemów

Problem	Możliwa przyczyna	Sugerowana poprawka
Akcja kończy się niepowodzeniem z śladem stosu	Błąd składni lub środowiska uruchomieniowego w pliku index.js	Używanie console.log() i sprawdzanie dzienników
Dane wejściowe są undefined	Nieprawidłowa nazwa danych wejściowych lub brakujące dane wejściowe	Zweryfikuj action.yml i sposób przekazywania danych wejściowych
Zmienne środowiskowe nie są ustawione	core.exportVariable lub process.env nie używane prawidłowo	Przejrzyj ustawienie zmiennych w kodzie
Nie znaleziono pliku	Brakujące ścieżki względne	Używanie __dirname lub pełne ścieżki do plików
Pamięć podręczna nie jest przywracana	Nieprawidłowe key lub path wartości	Sprawdź konfigurację i klucze pamięci podręcznej

Używanie rejestrowania do debugowania

Rejestrowanie komunikatów za pomocą core.info, core.debug oraz console.log.

const core = require('@actions/core');

core.info("This is an info message");
core.debug("This is a debug message");
console.log("This is a raw console log");

✅ Użyj pliku core.debug dla dzienników debugowania — są one wyświetlane tylko wtedy, gdy ACTIONS_STEP_DEBUG jest ustawiona na wartość true.

Włącz logowanie debugowania

Dzienniki debugowania na poziomie kroku można włączyć, ustawiając następujący wpis tajny:

ACTIONS_STEP_DEBUG=true

Aby włączyć dzienniki diagnostyczne modułu uruchamiającego, ustaw:

ACTIONS_RUNNER_DEBUG=true

Ustawianie wpisów tajnych na potrzeby debugowania

1. Przejdź do repozytorium GitHub.
2. Przejdź do Ustawienia>Sekrety i zmienne>Akcje.
3. Dodaj nowe wpisy tajne z następującymi nazwami i wartościami:
   • ACTIONS_STEP_DEBUG: true
   • ACTIONS_RUNNER_DEBUG: true

Inspekcja dzienników przepływu pracy

Gdy przepływ pracy zakończy się niepowodzeniem, kliknij na zadanie w karcie Akcje, które nie powiodło się. Rozwiń każdy krok, aby:

• Wyświetlanie szczegółowych dzienników
• Sprawdzanie standardowych danych wyjściowych (stdout)
• Zobacz kod zakończenia skryptów
• Identyfikowanie nieobsługiwanych wyjątków

🔍 Przykładowe dane wyjściowe dziennika

Error: Cannot find module '@actions/core'
Require stack:
- /home/runner/work/_actions/my-org/my-action/index.js

✅ Poprawka: Uruchom polecenie npm install @actions/core i zatwierdź node_modules (lub użyj ncc, aby powiązać akcję).

Testowanie akcji lokalnie

Act — narzędzie interfejsu wiersza poleceń do lokalnego uruchamiania GitHub Actions. Przykład:

act -j test

🛠 Pamiętaj, aby prawidłowo symulować środowisko Usługi GitHub podczas testowania lokalnego.

Eleganckie obsługiwanie błędów

Przechwyć wyjątki i zakończyć się niepowodzeniem przy użyciu przydatnych komunikatów:

try {
  // your logic
} catch (error) {
  core.setFailed(`Action failed with error: ${error.message}`);
}

🔁 Dzięki temu usługa GitHub zatrzymuje przepływ pracy po błędzie i zapewnia czytelne dzienniki.

Najlepsze rozwiązania dotyczące debugowania akcji języka JavaScript

Praktyka	Opis
Korzystanie z pliku core.debug()	Ukryj szczegółowe dzienniki, chyba że debugowanie jest włączone.
Weryfikowanie action.yml	Upewnij się, że dane wejściowe i wyjściowe są poprawnie zdefiniowane.
Kod pakietu	Użyj @vercel/ncc, aby skompilować kod JavaScript w jednym pliku. Zmniejsza to zależności i zapewnia, że wszystkie wymagane moduły są uwzględniane, uniemożliwiając błędy środowiska uruchomieniowego spowodowane brakującymi plikami.
Testowanie za pomocą działania	Symuluj lokalnie przebiegi dla szybszych iteracji.
Korzystanie z funkcji try/catch	Zapobiegaj niepowodzeniom przepływów pracy w trybie dyskretnym.

Rozwiązywanie problemów z akcjami kontenera platformy Docker

Kontenery Docker służą do hermetyzacji złożonych narzędzi i środowisk w przepływach pracy GitHub Actions. Jednak debugowanie tych akcji może być trudniejsze niż akcje języka JavaScript ze względu na ich izolowane środowisko uruchomieniowe. Ta lekcja przeprowadzi Cię przez proces identyfikowania, diagnozowania i rozwiązywania problemów z akcjami opartymi na platformie Docker.

Typowe problemy dotyczące akcji kontenera platformy Docker

Problem	Przyczyna	Sugerowana poprawka
Nie można uruchomić akcji	ENTRYPOINT lub CMD nieprawidłowo skonfigurowany	Potwierdź, że ENTRYPOINT Dockerfile jest używany poprawnie
Brakujące zależności	Zależności nie są zainstalowane lub nieprawidłowo skonfigurowane	Upewnij się, że wszystkie pakiety są zainstalowane w obrazie
Nie odebrano danych wejściowych	INPUT_ zmienne środowiskowe, do których nie uzyskiwano dostępu	Użyj process.env.INPUT_<INPUT_NAME> (lub odpowiednik powłoki)
Nie znaleziono pliku	Nieprawidłowa ścieżka pliku wewnątrz kontenera	Używanie ścieżek bezwzględnych lub weryfikowanie struktury katalogów
Odmowa uprawnień	Plik lub skrypt nie ma uprawnień do wykonywania	Dodawanie RUN chmod +x <script> w pliku Dockerfile
Błędy związane z siecią	Usługi zewnętrzne są niedostępne	Weryfikowanie ustawień sieci i logiki ponawiania prób

Omówienie cyklu życia akcji platformy Docker

Przed rozwiązaniem problemów warto zrozumieć, jak działają akcje kontenera platformy Docker.

1. Wyzwalacz przepływu pracy

Przepływ pracy GitHub Actions jest uruchamiany w odpowiedzi na skonfigurowane zdarzenie, takie jak push, pull_request lub ręczne workflow_dispatch.

2. Konfiguracja biegacza

GitHub udostępnia nową maszynę wirtualną (moduł uruchamiający), aby wykonać przepływ pracy. Uruchamiacz przygotowuje środowisko, pobierając definicje akcji i rozwiązując zależności.

3. Rozwiązanie akcji

Jeśli akcja zostanie określona runs.using: docker w pliku action.yml , usługa GitHub rozpozna ją jako akcję opartą na platformie Docker.

4. Kompilacja obrazu lub ściąganie

GitHub kompiluje obraz Docker zdefiniowany w akcji Dockerfile lub pobiera przygotowany obraz, jeśli jest to określone. Ten obraz definiuje środowisko, w którym jest uruchamiany kod akcji.

5. Wykonywanie kontenera

Uruchamiacz uruchamia kontener Docker, montuje obszar roboczy i wprowadza zmienne środowiskowe, w tym sekrety i wejścia zdefiniowane w przepływie pracy.

6. Działanie punktu wejścia

Usługa GitHub wykonuje entrypoint polecenie z pliku Dockerfile wewnątrz kontenera. W tym miejscu jest uruchamiana logika akcji niestandardowej, zazwyczaj skrypt lub aplikacja.

7. Obsługa wyników

Wszystkie dane wyjściowe ustawione przez akcję kontenera są przechwytywane przez moduł uruchamiający i przekazywane do kolejnych kroków w przepływie pracy. Po zakończeniu kontener jest wyłączany, a uruchamiacz zostaje odrzucony.

Uwaga: akcje kontenera platformy Docker są uruchamiane w czystym, izolowanym środowisku. Stan systemu plików, zainstalowane narzędzia i zmienne środowiskowe muszą być zdefiniowane w pliku Dockerfile.

Techniki debugowania

1. Dodaj logowanie

Użyj instrukcji echo, printf lub rejestrowania w skrypcie punktu wejścia:

echo "Starting Docker action..."
echo "Input VALUE: $INPUT_VALUE"

Zarejestruj wszystkie krytyczne dane wejściowe i kroki, aby zdiagnozować, gdzie wystąpi awaria.

2. Kompilowanie i testowanie lokalne

Użyj platformy Docker na maszynie, aby symulować zachowanie kontenera:

docker build -t my-action .
docker run -e INPUT_NAME=value my-action

Upewnij się, że zmienne środowiskowe naśladują te, które ustawia GitHub.

3. Użyj act CLI do symulacji przepływów pracy w GitHub

Zainstaluj narzędzie "act", aby uruchamiać lokalnie przepływy pracy GitHub.

act -j test-job

Doskonałe rozwiązanie do testowania akcji Docker w workflowach bez wysyłania do GitHub.

4. Weryfikowanie konfiguracji pliku Dockerfile

Upewnij się, że zdefiniowano element ENTRYPOINT lub CMD. Skopiuj skrypty do obrazu i nadaj im uprawnienia do wykonywania:

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

5. Sprawdzanie dzienników usługi GitHub

Kliknij na nieudany przebieg przepływu pracy, rozwiń każdy krok i zanalizuj:

• Dzienniki kompilacji platformy Docker
• Standardowe dane wyjściowe i standardowy błąd z kontenera
• Kody zakończenia i ślady stosu 🔍 często ujawniają brakujące pakiety, problemy ze składnią lub błędy uprawnień.

Przykład: błąd punktu wejścia

Error: container_linux.go:380: starting container process caused "exec: \"/entrypoint.sh\": permission denied"

✅ Poprawka: Dodaj moduł RUN chmod +x /entrypoint.sh w pliku Dockerfile.

Mapowanie zmiennych środowiskowych

Dane wejściowe usługi GitHub	Zmienna środowiskowa platformy Docker
with: name: test	INPUT_NAME=test
GITHUB_WORKSPACE	Zamapowane na /github/workspace
GITHUB_EVENT_NAME	Zdarzenie, które wyzwoliło przepływ pracy

echo "Input was $INPUT_NAME"
echo "Working dir: $GITHUB_WORKSPACE"

** Korzystanie z tajemnic rozwiązywania problemów

Włącz dodatkowe rejestrowanie, dodając te dane poufne do swojego repozytorium lub organizacji.

Klucz tajny	opis
ACTIONS_STEP_DEBUG	Włącza logi debugowania
ACTIONS_RUNNER_DEBUG	Włącza diagnostykę modułu uruchamiającego

Najlepsze rozwiązania dotyczące debugowania akcji platformy Docker

Najlepsze rozwiązanie	Dlaczego
Używaj logowania obficie	Pomaga śledzić punkty awarii
Zawsze ustawiaj tryb chmod +x	Unikaj błędów uprawnień w skryptach powłoki
Weryfikowanie danych wejściowych w skrycie	Przechwyć brakujące lub źle sformułowane dane wejściowe wcześnie
Minimalizowanie zależności kontenera	Mniejsze obrazy są łatwiejsze do debugowania
Testowanie lokalne za pomocą polecenia docker run lub act	Szybsze iteracji i natychmiastowe opinie