Tworzenie niestandardowej akcji usługi GitHub

  • 8 min

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

Diagram przedstawiający trzy typy funkcji GitHub Actions; Akcje docker, JavaScript i złożone kroki uruchamiania.

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.

Metadane i składnia potrzebne do utworzenia akcji

Podczas tworzenia lub przeglądania akcji usługi GitHub pierwszym krokiem jest przejrzenie action.yml pliku w celu oceny, które dane wejściowe, dane wyjściowe, opis, uruchomienia i inne informacje o konfiguracji wymagają działania. Niektóre z tych parametrów są wymagane, a inne są opcjonalne. Plik action.yml definiuje następujące informacje o akcji:

Parametr opis Wymagania
Nazwisko Nazwa akcji. Pomaga wizualnie zidentyfikować akcję w zadaniu. tak
opis Podsumowanie działania. tak
Dane wejściowe Parametry wejściowe umożliwiają określenie danych, których akcja oczekuje się użyć w czasie wykonywania. Te parametry stają się zmiennymi środowiskowymi w module uruchamiającym. nie
Dane wyjściowe Parametry wyjściowe umożliwiają określenie danych, których kolejne akcje mogą być używane później w przepływie pracy po uruchomieniu akcji definiującej te dane wyjściowe. nie
Przebiegi Polecenie do uruchomienia po wykonaniu akcji. tak
Marka Kolor i ikona pióra do użycia w celu utworzenia wskaźnika w celu spersonalizowania i odróżnienia akcji w witrynie GitHub Marketplace. nie

Dane wejściowe

Dane wejściowe to parametry, które umożliwiają określenie danych, których akcja oczekuje się użyć w czasie wykonywania. Usługa GitHub przechowuje te parametry wejściowe jako zmienne środowiskowe.

Poniżej znajduje się przykład listy danych wejściowych dla akcji. Dane firstNameStudent wejściowe są opcjonalne, a studentGrade dane wejściowe są wymagane.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Dane wyjściowe

Dane wyjściowe to parametry, które umożliwiają deklarowanie danych. Należy pamiętać, że akcje uruchamiane później w przepływie pracy mogą używać danych wyjściowych zadeklarowanych w poprzedniej akcji uruchamiania.

Poniższy przykład to proste dane wyjściowe do deklarowania średniej klasy uczniów:

outputs:
  average:
    description: 'The average grade of the students'

Przebiegi

Jak wspomniano wcześniej, akcja musi zawierać instrukcję definiującą runs polecenie niezbędne do wykonania akcji. W zależności od sposobu tworzenia akcji — niezależnie od tego, czy używasz kontenera platformy Docker, języka JavaScript, czy złożonych kroków uruchamiania — składnia runs jest definiowana inaczej.

runs dla akcji platformy Docker

Akcje kontenera platformy Docker wymagają runs instrukcji w celu skonfigurowania obrazu używanego przez akcję platformy Docker z następującymi argumentami:

  • using: Musi być ustawiona wartość , aby docker uruchomić akcję kontenera platformy Docker
  • image: obraz platformy Docker używany jako kontener do uruchamiania akcji
runs:
  using: 'docker'
  image: 'Dockerfile'

runs dla akcji języka JavaScript

Akcje języka JavaScript wymagają, aby instrukcja podejmiła runs dwa następujące argumenty:

  • using: aplikacja używana do wykonywania kodu zgodnie z definicją w main
  • main: plik zawierający kod akcji; aplikacja zdefiniowana w using pliku wykonuje ten plik

Na przykład poniżej przedstawiono instrukcję runs dla akcji języka JavaScript przy użyciu Node.js:

runs:
  using: 'node12'
  main: 'main.js'

runs dla złożonych akcji kroków uruchamiania

Akcje złożonych kroków uruchamiania wymagają, aby instrukcja podejmiła runs następujące trzy argumenty:

  • using: Musi być ustawiona wartość , aby "composite" uruchomić złożony krok przebiegu
  • steps: Uruchamianie kroków w celu uruchomienia akcji
  • steps[*].run: Polecenie, które chcesz uruchomić (może być wbudowane lub skrypt w repozytorium akcji)

Na przykład poniżej przedstawiono instrukcję runs dla akcji złożonych kroków uruchamiania, która spowoduje uruchomienie skryptu w ścieżce /test/script/shpliku :

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Marka

Opcjonalna, ale zabawna funkcja to możliwość dostosowania wskaźnika akcji. Znaczek jest wyświetlany obok nazwy akcji w witrynie GitHub Marketplace. Aby utworzyć znaczek, możesz użyć koloru i ikony Pióro . W przypadku znakowania należy określić ikonę i kolor, którego chcesz użyć.

branding:
  icon: 'shield'  
  color: 'blue'

Oto przykład wskaźnika akcji Wyewidencjonuj w witrynie GitHub Marketplace:

Zrzut ekranu przedstawiający znakowanie akcji w witrynie GitHub Marketplace.

Polecenia przepływu pracy

Tworzenie przepływu pracy jest dość proste, o ile można znaleźć odpowiednie akcje dla kroków. W niektórych przypadkach może być konieczne utworzenie własnych akcji w celu osiągnięcia pożądanych wyników, ale możesz użyć poleceń przepływu pracy, aby dodać kolejny poziom dostosowywania do przepływów pracy.

Polecenia przepływu pracy umożliwiają komunikowanie się z maszyną modułu uruchamiającego funkcję GitHub Actions przez drukowanie sformatowanych wierszy tekstu w konsoli programu . Możesz użyć tych poleceń przepływu pracy z poleceniami powłoki lub w ramach akcji niestandardowych. Polecenia przepływu pracy są przydatne, ponieważ umożliwiają udostępnianie informacji między krokami przepływu pracy, drukowaniem komunikatów debugowania lub błędów w konsoli, ustawianie zmiennych środowiskowych, ustawianie parametrów wyjściowych lub dodawanie do ścieżki systemowej.

Większość poleceń przepływu pracy używa echo polecenia w następującym określonym formacie, podczas gdy inne mogą być wywoływane przez zapisanie w pliku:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Poniżej przedstawiono kilka podstawowych przykładów rejestrowania komunikatów dotyczących drukowania komunikatu debugowania, komunikatu o błędzie, komunikatu o błędzie lub komunikatu ostrzegawczego do konsoli:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

Można również utworzyć komunikat do drukowania w dzienniku przy użyciu nazwy pliku (pliku), numeru wiersza (wiersza) i numeru kolumny (kolumny), w której wystąpił błąd. Komunikaty ostrzegawcze są wyświetlane w żółtym wyróżnieniu z tekstem "ostrzeżenie", a komunikaty o błędach są wyświetlane w czerwonym wyróżnieniu z tekstem "błąd".

echo "::error file=app.js,line=10,col=15::Something went wrong"

Należy pamiętać, że te polecenia przepływu pracy muszą znajdować się w jednym wierszu. Znaki, które zakłócają analizowanie, takie jak przecinki i podziały wierszy, muszą być zakodowane pod adresem URL.

Na przykład następujący tekst jest komunikatem wielowierszowym:

This text spans
across multiple lines

Ten komunikat powinien być zakodowany w sposób pokazany tutaj:

This text spans%0Aacross multiple lines

Oprócz poleceń przepływu pracy można ustawić kody zakończenia, aby ustawić stan akcji. Jest to ważne, ponieważ podczas pracy z zadaniami w przepływie pracy kod zakończenia, który zakończył się niepowodzeniem, spowoduje zatrzymanie wszystkich współbieżnych akcji i anulowanie wszelkich przyszłych akcji. Jeśli tworzysz akcję języka JavaScript, możesz użyć pakietu zestawu narzędzi @actions/core actions, aby zarejestrować komunikat i ustawić kod zakończenia niepowodzenia. Jeśli tworzysz akcję kontenera platformy Docker, możesz ustawić kod zakończenia błędu w skry skryptie entrypoint.sh .