GitHub Actions: jak wprowadzić lockfile w pierwszym PR

Wprowadź plik lockfile w jednym workflow GitHub Actions. Zespół powinien umieć wyjaśnić i sprawdzić tę zmianę. Ustal, jakie commity akcji zapisuje plik, zabezpiecz osobno nieobjęte nim dane wejściowe i wyznacz osobę do review kolejnych aktualizacji. Pierwszym użytecznym wynikiem będzie pull request z jasno opisanym zakresem i udanym uruchomieniem na sprawdzanej rewizji.

Przy poprawie bezpieczeństwa całego repozytorium brzmi to skromnie. Mały zespół może jednak taką pracę doprowadzić do końca. Wygenerowany plik staje się przydatny, gdy recenzenci rozumieją, jaki kod wykonywalny zatwierdzili i co nadal może się zmieniać w jego otoczeniu.

GitHub udostępnił pliki lockfile dla workflow 28 października we wskazanych planach Free, Team i Enterprise Cloud, w tym Enterprise Cloud z rezydencją danych. Instrukcja Hugo van Kemenadego z 11 listopada ponownie zwróciła uwagę na ich wdrożenie. Pytanie dla zespołu brzmi: jak wprowadzić to zabezpieczenie, nie tracąc z oczu reszty workflow?

Co zatwierdzasz, wprowadzając lockfile dla workflow

Plik lockfile zapisuje commity akcji, które ma wykonać objęty nim workflow, wraz z zależnościami przechodnimi między akcjami. Według opisu mechanizmu w dokumentacji GitHub runner wymusza użycie tak rozstrzygniętych zależności, sprawdza tożsamość repozytorium źródłowego i odrzuca zapisany commit, jeśli nie jest on osiągalny z zapisanej referencji upstream.

Masz więc konkretny zestaw zależności do zatwierdzenia. Widoczna referencja akcji może być łatwa do odczytania, ale wykonanie tej akcji może wymagać uruchomienia kolejnych. Ujęcie tych zależności w pliku daje recenzentom pełniejszy obraz kodu, który zostanie wykonany.

Zatwierdzenie nadal wymaga oceny. Zapisany commit może zawierać kod, który czyta więcej plików, łączy się z nową usługą lub korzysta z uprawnień, których workflow w ogóle nie powinien dostać. Plik lockfile może wiernie utrwalić również taki wybór. Dlatego nadal obowiązują zalecenia GitHub dotyczące bezpiecznego użycia: sprawdzaj źródła akcji, ograniczaj uprawnienia tokenów i ostrożnie obchodź się z niezaufaną zawartością pull requestów.

Podczas review pamiętaj o dwóch pytaniach: „Czy to uruchomienie użyje zapisanego kodu akcji?” i „Czy ten kod powinien móc się tutaj wykonać?” Plik lockfile pomaga odpowiedzieć na pierwsze. Drugie zależy od kodu, zdarzenia wyzwalającego, runnera i dostępnych mu uprawnień.

Ogranicz pierwszy pull request do zrozumiałej zmiany

Wyobraź sobie czteroosobowy startup z workflow do testów, workflow do wdrożeń, współdzielonym workflow wielokrotnego użytku i krokiem Docker. To hipotetyczny przykład wdrożenia. Zacznij od workflow, którego cel, dane wejściowe i oczekiwane wyniki potrafi wyjaśnić osoba za niego odpowiedzialna. W tym przykładzie przyjmijmy, że będzie to workflow testowy.

Przed generowaniem pliku opisz w PR, jak workflow działa obecnie. Wskaż zdarzenie, które go uruchamia, pochodzenie kodu w katalogu roboczym, uprawnienia tokena, dostępne sekrety i używany runner. Jeśli workflow mogą uruchamiać osoby spoza zespołu, uwzględnij ich kod jako dane wejściowe. Nawet pozornie zwyczajne zadanie testowe może przebiegać przez istotną granicę zaufania.

Instrukcja GitHub pozwala ograniczyć generowanie do jednego workflow. Dzięki temu pierwszą zmianę da się rzetelnie sprawdzić. Postępuj zgodnie z aktualną instrukcją instalacji i generowania, a następnie obejrzyj zarówno zmiany w workflow, jak i actions.lock.

Zwróć szczególną uwagę na akcje lokalne. Referencja ./ korzysta z pobranej zawartości katalogu roboczego. Zmiana na $/ kieruje ją na commit samego workflow. Może to zmienić zachowanie, jeśli rewizja workflow różni się od rewizji pobranego kodu. Zanim zaakceptujesz taką zmianę, sprawdź, czy wskazuje zamierzone źródło. Nierozstrzygnięta zależność lokalna wymaga zbadania.

Pierwszy PR powinien zawierać dość dowodów, by inna osoba z zespołu mogła podjąć decyzję:

1. Zakres: workflow obejmowany plikiem lockfile oraz te pozostawione na później.
2. Rozstrzygnięcie zależności: wygenerowane zmiany zależności, w tym akcji przechodnich.
3. Zachowanie: każda zmiana lokalnych referencji lub inna modyfikacja workflow.
4. Walidacja: metoda weryfikacji i udane uruchomienie workflow na rewizji poddawanej review.
5. Wyjątki: wykonywalne dane wejściowe, których plik lockfile nie obejmuje, z osobą odpowiedzialną i decyzją dla każdego przypadku.

Zielony wynik testów oznacza, że obserwowane uruchomienie zakończyło się pomyślnie. Przeczytaj też wyniki odpowiednich zadań: czy wykonano zamierzone testy, czy powstały oczekiwane artefakty i czy któryś krok zaczął działać inaczej? Umieść link do uruchomienia obok diffu, aby recenzent mógł sprawdzić jedno i drugie.

Uwzględnij dane wejściowe poza plikiem lockfile

Granice pliku lockfile mają największe znaczenie tam, gdzie workflow wywołuje coś innego. Oficjalny README narzędzia CLI opisuje ograniczenia, w tym wywołania zewnętrznych workflow wielokrotnego użytku i obrazy kontenerów. W pierwszym PR krótko zapisz, jak kontrolowane są te dane wejściowe.

Workflow wielokrotnego użytku wymagają szczególnej uwagi. Dokumentacja mechanizmu GitHub wyjaśnia, że plik lockfile po stronie wywołującej nie przypina wywołań przez jobs.<job_id>.uses do konkretnego commita. Aby przypiąć wywołanie workflow wielokrotnego użytku, użyj pełnego SHA commita. Zależności akcji wewnątrz wywoływanego workflow należą do pliku lockfile w jego repozytorium. Samo sprawdzenie pliku wygenerowanego po stronie wywołującej nie wystarcza do ustalenia zakresu w wywoływanym repozytorium.

W hipotetycznym startupie do PR dotyczącego workflow testowego można dołączyć poniższą tabelę. Przed review zastąp przykładowe role konkretnymi nazwiskami.

Wiersz o pobieranym narzędziu wynika z tego, co wykonuje powłoka. Polecenie może pobrać kod wykonywalny spoza referencji akcji zapisanych w pliku lockfile. Sprawdź ten sposób pobierania i ustal, jak zespół będzie identyfikować oraz sprawdzać artefakt. Niewyjaśnione dane wejściowe potraktuj jako jawny wyjątek wymagający decyzji.

Osobno sprawdź dostęp podczas wykonywania kodu. Obrazy runnerów, dane wejściowe i dane uwierzytelniające pozostają poza zapisanym rozstrzygnięciem zależności akcji. Nasza checklista dostępu w sandboxach agentów rozwija szersze pytanie: co uruchomienie może odczytać, zmienić i z czym może się połączyć? Zastosuj je także do CI, bez zakładania, że sam plik zależności daje odpowiedź.

Wyznacz osobę odpowiedzialną za kolejną aktualizację

Przy następnej aktualizacji decyzja o wdrożeniu staje się stałą praktyką utrzymania. Zapisz, kto sprawdza zmiany w pliku lockfile, jakich dowodów oczekuje i jak obejmowane nim będą nowo dodawane workflow.

GitHub w instrukcji egzekwowania plików lockfile zaleca pilotaż przed szerszym wprowadzeniem wymagań. Dependabot utrzymuje wpisy dla już objętych nimi workflow, ale nie dodaje nowych automatycznie. Uwzględnij więc tę konfigurację w checkliście do review nowego workflow, zamiast zakładać, że bot aktualizujący sam wykryje i wykona zadanie.

Dobierz weryfikację do sprawdzanego pytania. Dokumentacja CLI odróżnia lokalną kontrolę kompletności bez połączenia z siecią przez --verify-local od sprawdzania pochodzenia online przez --verify. Zapisz, którą przeprowadzono, i zbadaj błędy, zanim rozszerzysz zakres. Udana lokalna kontrola kompletności i sprawdzenie pochodzenia online dostarczają różnych dowodów.

Dokumentacja CLI opisuje też ograniczenie, o którym recenzenci powinni pamiętać: cofnięcie zmiennej referencji do wcześniejszego punktu w jej historii nie zostaje wykryte. Sprawdź faktyczną zmianę zależności również wtedy, gdy weryfikacja przechodzi. Ustal, jaki kod się zmienił, czy zmieniły się zachowanie lub wymagane uprawnienia i czy wybrana rewizja jest rzeczywiście tą, którą chcesz zatwierdzić.

Jeśli organizacja korzysta z trybów stopniowego wprowadzania reguł, sprawdź ich dostępność przed obiecaniem konkretnego procesu. Zgodnie z dokumentacją GitHub tryb Evaluate jest dostępny w Enterprise Cloud. Zespół bez tego trybu nadal może zacząć od jednego sprawdzonego workflow i obowiązkowej weryfikacji.

Rozszerz wdrożenie, gdy odpowiedzialna osoba potrafi wyjaśnić, co obejmuje pilotaż, jakie są wyjątki i jak przebiegają aktualizacje. Workflow wdrożeniowy potraktuj jako osobną decyzję, ponieważ ma inne skutki i może otrzymywać inne dane uwierzytelniające.

Zachowaj dowody weryfikacji przy zgłoszeniu dotyczącym CI

Rutynowe wprowadzenie pliku lockfile dokumentuj w PR zespołu inżynierskiego. Jeśli praca wynika ze zgłoszenia podatności, powiąż zgłoszenie z tym PR i dowodami weryfikacji. Zapisz zakres narażenia, wprowadzone zmiany, sprawdzoną rewizję i kwestie nadal nierozstrzygnięte.

Odtworzenie przebiegu incydentu to osobne zadanie. Nasz poradnik o przejęciu repozytorium i granicach procesu wydawania wyjaśnia, jak ustalić, czy podejrzany kod źródłowy trafił do wydania lub jego odbiorców. Sięgnij po niego, gdy pojawią się takie pytania. Wypełnienie tabeli wdrożenia nie pozwala ustalić wcześniejszego narażenia.

W Kit obsługa zgłoszeń podatności pozwala przechowywać razem informacje o osobie odpowiedzialnej za zgłoszenie, linki do dowodów technicznych i decyzję człowieka o weryfikacji. Cykl obsługi rozdziela rozwiązanie problemu od weryfikacji poprawki, a osoba sprawdzająca może dodać notatkę. Zespół inżynierski nadal generuje plik lockfile, analizuje workflow i ustala, czy poprawka działa. Kit nie przeprowadza tej oceny ani nie wymaga dokumentacji dowodowej przy każdej weryfikacji.

W pierwszym PR wybierz jeden workflow, sprawdź zmiany w kodzie wykonywalnym, wskaż nieobjęte dane wejściowe i wyznacz osobę do kolejnej aktualizacji. Jeśli przyczyną pracy było zgłoszenie bezpieczeństwa, umieść przy nim odnośniki do PR i uruchomienia. Zostaw kolejnemu recenzentowi dość dowodów, by mógł zrozumieć, co dokładnie zespół zatwierdził.