Publikowanie niestandardowej akcji usługi GitHub

Zakończone

W tym miejscu dowiesz się, jak wybrać właściwą widoczność akcji, najlepsze rozwiązania dotyczące dokumentowania i przechowywania wersji akcji oraz sposobu publikowania akcji w witrynie GitHub Marketplace.

Wybierz lokalizację dla akcji

Podczas tworzenia akcji ważne jest, aby najpierw zdecydować, gdzie ma być aktywna ta akcja, oraz widoczność tej akcji, niezależnie od tego, czy będzie public to czy private. Widoczność akcji określa, które zalecenia i wymagania są potrzebne do wydania tej akcji. Przyjrzyjmy się bliżej tym dwóm opcjom widoczności.

Publiczne

Przepływy pracy w dowolnym repozytorium mogą używać akcji publicznych. Jeśli tworzysz akcję z zamiarem udostępnienia go jako typu open source lub udostępnisz go publicznie za pośrednictwem witryny GitHub Marketplace, zalecamy (i w większości przypadków jest to wymagane), że akcja ma własne repozytorium, zamiast grupować go za pomocą innego kodu aplikacji. Umożliwia to przechowywanie wersji, śledzenia i wydawania akcji tak samo jak w przypadku każdego innego oprogramowania. Ułatwia to społeczności usługi GitHub odnajdywanie akcji, zawęża zakres bazy kodu dla deweloperów, którzy naprawiają problemy i rozszerzają akcję, i oddziela przechowywanie wersji akcji od przechowywania wersji innego kodu aplikacji.

Prywatne

Gdy akcja znajduje się w repozytorium prywatnym, tylko przepływy pracy w tym samym repozytorium mogą używać akcji. Za pomocą akcji prywatnych można przechowywać pliki akcji w dowolnej lokalizacji w repozytorium. Jeśli planujesz połączyć akcję, przepływ pracy i kod aplikacji w jednym repozytorium, zalecamy zapisanie akcji w .github katalogu. Przykład: .github/actions/action-a i .github/actions/action-b.

Dokumentowanie akcji

Może to być bardzo frustrujące, aby użyć nowego narzędzia lub aplikacji, gdy dokumentacja jest niejasna lub nawet brakuje. Ważne jest, aby uwzględnić dobrą dokumentację z akcją, aby inni mogli zobaczyć, jak to działa, niezależnie od tego, czy zamierzasz udostępnić ją publicznie, czy prywatnie. Pierwszą rzeczą do zrobienia jest utworzenie dobrego pliku README.md dla akcji.

Plik README.md jest często pierwszym miejscem, w których deweloperzy będą sprawdzać, jak działa akcja. Jest to doskonałe miejsce do uwzględnienia wszystkich ważnych informacji dotyczących akcji. Poniżej znajduje się niewyczerpująca lista rzeczy, które należy uwzględnić:

• Szczegółowy opis działania.
• Wymagane argumenty wejściowe i wyjściowe.
• Opcjonalne argumenty wejściowe i wyjściowe.
• Wpisy tajne używane przez akcję.
• Zmienne środowiskowe używane przez akcję.
• Przykład użycia akcji w przepływie pracy.

Ogólnie rzecz biorąc, plik powinien zawierać wszystko, README.md co użytkownik powinien wiedzieć, aby używać akcji. Jeśli uważasz, że może to być przydatne informacje, uwzględnij je w pliku README.md.

Zwalnianie i przechowywanie wersji akcji

Jeśli tworzysz akcję dla innych osób do użycia, niezależnie od tego, czy jest ona publiczna, czy prywatna, należy zdefiniować strategię zarządzania wydaniami, aby kontrolować sposób dystrybucji aktualizacji. Aktualizacje wersji głównych, w tym niezbędne poprawki krytyczne i poprawki zabezpieczeń, które mają wpływ na zgodność, muszą być jasno udokumentowane.

Dobre rozwiązania dotyczące zarządzania wydaniami i wersjami

Dobra strategia zarządzania wydaniami powinna obejmować zalecenia dotyczące przechowywania wersji. Użytkownicy nie powinni odwoływać się do domyślnej gałęzi akcji z akcją. Dzieje się tak, ponieważ gałąź domyślna, która prawdopodobnie zawiera najnowszy kod (który może być stabilny lub może nie być stabilny), może spowodować przerwanie przepływu pracy. Zamiast tego zalecamy użytkownikom określenie wersji głównej podczas korzystania z akcji i przekierowanie ich tylko do bardziej konkretnej wersji, jeśli wystąpią problemy. Mogą to zrobić, konfigurując przepływ pracy funkcji GitHub Actions w celu kierowania tagu, algorytmu SHA zatwierdzenia lub określonej gałęzi o nazwie dla wydania. Przyjrzyjmy się bliżej tym opcjom wydania.

Tagi

Tagi mogą być dobrym sposobem zarządzania wydaniami dla akcji. Korzystając z tagów, użytkownicy mogą łatwo rozróżniać wersje główne i pomocnicze. Poniżej przedstawiono listę przydatnych rozwiązań, które należy wziąć pod uwagę podczas tworzenia wersji:

• Utwórz i zweryfikuj wydanie w gałęzi wydania (na release/v1przykład ) przed utworzeniem tagu wydania (na przykład v1.0.2).
• Użyj semantycznego przechowywania wersji.
• Przenieś tag wersji głównej (na przykład v1, v2), aby wskazać identyfikator ref usługi Git bieżącej wersji.
• Wprowadzenie nowego tagu wersji głównej (v2) dla zmian, które spowodują przerwanie istniejących przepływów pracy.
• Wydaj wersje główne z tagiem beta, aby wskazać ich stan; na przykład v2-beta. Tag można usunąć -beta , gdy wydanie będzie gotowe.

Oto kilka przykładów każdej opcji.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Używanie algorytmu SHA zatwierdzenia

Tagi są przydatne i powszechnie używane, ale jednym z wad używania tagów jest to, że można je usunąć lub przenieść. W przypadku usługi Git każde zatwierdzenie otrzymuje obliczoną wartość SHA, która jest unikatowa i nie można jej modyfikować. Użycie zatwierdzenia algorytmu SHA do przechowywania wersji zapewni najbardziej niezawodny i bezpieczny sposób przechowywania wersji i używania akcji. Jednak często w usłudze Git można skrócić skrót SHA do pierwszych kilku znaków, a usługa Git rozpozna odwołanie. Jeśli używasz algorytmu SHA zatwierdzenia do zarządzania wydaniami, musisz użyć pełnej wartości SHA, a nie skróconej wartości.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Publikowanie akcji w witrynie GitHub Marketplace

Gdy wszystko będzie gotowe do udostępnienia akcji społeczności usługi GitHub, możesz opublikować ją w witrynie GitHub Marketplace i skontaktować się z milionami użytkowników usługi GitHub. Akcje opublikowane w witrynie GitHub Marketplace są publikowane natychmiast, jeśli zostaną spełnione wszystkie wymagania. Akcje, które nie spełniają wymagań, należy przejrzeć przez usługę GitHub przed opublikowaniem. Należy się upewnić, że repozytorium zawiera tylko plik metadanych, kod i pliki niezbędne do wykonania akcji. Utworzenie pojedynczego repozytorium dla akcji umożliwia tagowanie, wydawanie i pakowanie kodu w ramach jednej lekcji. Usługa GitHub używa również metadanych akcji na stronie witryny GitHub Marketplace.

Poniżej przedstawiono wymagania dotyczące publikowania akcji w witrynie GitHub Marketplace. Mają zastosowanie zarówno do akcji opartych na kontenerze platformy Docker, jak i akcji opartych na języku JavaScript:

• Akcja musi znajdować się w repozytorium publicznym.
• Każde repozytorium musi zawierać jedną akcję.
• Plik metadanych akcji (action.yml lub action.yaml) musi znajdować się w katalogu głównym repozytorium.
• Plik name metadanych akcji musi być unikatowy w witrynie GitHub Marketplace.
  • Nazwa nie może być zgodna z użytkownikiem lub organizacją w usłudze GitHub, chyba że właściciel użytkownika lub organizacji publikuje akcję. Na przykład tylko organizacja usługi GitHub może opublikować akcję o nazwie github.
  • Element name nie może być zgodny z istniejącą kategorią witryny GitHub Marketplace.
  • Element name nie może być zgodny z istniejącą funkcją usługi GitHub.

Możesz dodać utworzoną akcję do witryny GitHub Marketplace, oznaczając ją jako nową wersję, a następnie publikując ją. Istnieje kilka kroków z przewodnikiem w usłudze GitHub, które umożliwiają opublikowanie wydania akcji. Więcej informacji na temat tych kroków można znaleźć w sekcji Podsumowanie na końcu tego modułu.