Dostosowywanie i rozszerzanie przepływów pracy żądań ściągnięcia przy użyciu stanu żądania ściągnięcia

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Żądania ściągnięcia to doskonałe narzędzie ułatwiające przeglądy kodu i zarządzanie przenoszeniem kodu w repozytorium. Zasady gałęzi wymuszają jakość kodu podczas procesu żądania ściągnięcia, ustanawiając wymagania, które należy wykonać dla każdej zmiany kodu. Te zasady umożliwiają zespołom wymuszanie wielu najlepszych rozwiązań związanych z przeglądaniem kodu i uruchamianiem zautomatyzowanych kompilacji, ale wiele zespołów ma dodatkowe wymagania i walidacje do wykonania w kodzie. Aby uwzględnić te potrzeby indywidualne i niestandardowe, usługa Azure Repos oferuje stany żądań ściągnięcia. Stan żądania ściągnięcia integruje się z przepływem pracy żądania ściągnięcia i umożliwia usługom zewnętrznym programowe wylogowanie się ze zmianą kodu przez skojarzenie prostych informacji o typie powodzenia/niepowodzenia z żądaniem ściągnięcia. Opcjonalnie żądania ściągnięcia mogą być blokowane do momentu zatwierdzenia zmiany przez usługę zewnętrzną.

Integracja z przepływem pracy żądania ściągnięcia obejmuje kilka różnych pojęć:

• Stan żądania ściągnięcia — umożliwia usługom kojarzenie informacji o powodzeniu/niepowodzeniu z żądaniem ściągnięcia.
• Zasady stanu — udostępnia mechanizm blokowania ukończenia żądania ściągnięcia, dopóki stan żądania ściągnięcia nie wskazuje powodzenia.
• Akcje niestandardowe — umożliwia rozszerzenie menu stanu przy użyciu rozszerzeń usług Azure DevOps Services.

W tym temacie dowiesz się więcej na temat stanów żądań ściągnięcia i sposobu ich użycia do integracji z przepływem pracy żądania ściągnięcia.

Stan żądania ściągnięcia

Stan żądania ściągnięcia umożliwia usługom kojarzenie prostych informacji o typie powodzenia/niepowodzenia z żądaniem ściągnięcia przy użyciu interfejsu API stanu. Stan składa się z czterech kluczowych fragmentów danych:

• Stan. Jeden z następujących wstępnie zdefiniowanych stanów: succeeded, , failedpending, notSet, notApplicablelub error.
• Opis. Ciąg opisujący stan użytkownika końcowego.
• Kontekst. Nazwa stanu — zazwyczaj opisująca jednostkę publikującą stan.
• URL. Link, w którym użytkownicy mogą uzyskać więcej informacji specyficznych dla stanu.

Zasadniczo stan to sposób, w jaki użytkownik lub usługa publikuje ocenę żądania ściągnięcia i zapewnia odpowiedź na pytania, takie jak:

• Czy zmiany spełniają wymagania?
• Gdzie mogę dowiedzieć się więcej o tym, co muszę zrobić, aby spełnić wymagania?

Spójrzmy na przykład. Rozważ usługę ciągłej integracji, która jest wymagana do utworzenia wszystkich zmian kodu w projekcie. Gdy usługa ocenia zmiany w żądaniu ściągnięcia, musi opublikować wyniki kompilacji i testów. W przypadku zmian, które przechodzą kompilację, stan podobny do tego może zostać opublikowany w żądaniu ściągnięcia:

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

Ten stan będzie wyświetlany użytkownikowi końcowemu w widoku Szczegóły żądania ściągnięcia:

• Jest state wyświetlany użytkownikowi przy użyciu ikony (zielony znacznik wyboru succeeded, czerwony X dla failed, zegar dla pending, i czerwony ! dla error).
• Zostanie description wyświetlony obok ikony, a context element jest dostępny w etykietce narzędzia.
• targetUrl Po zastosowaniu elementu opis zostanie renderowany jako link do adresu URL.

Aktualizowanie stanu

Usługa może zaktualizować stan żądania ściągnięcia dla pojedynczego żądania ściągnięcia, publikując dodatkowe stany, z których tylko najnowsze są wyświetlane dla każdego unikatowego contextżądania ściągnięcia. Publikowanie wielu stanów ułatwia użytkownikom zarządzanie oczekiwaniami. Na przykład opublikowanie pending stanu jest dobrym sposobem potwierdzenia użytkownikowi, że system otrzymał zdarzenie i rozpoczyna pracę. Użycie informacji description , takich jak następujące przykłady, może jeszcze bardziej pomóc użytkownikowi zrozumieć, jak działa system:

• "Kompilacja w kolejce"
• "Kompilacja w toku"
• "Kompilacja powiodła się"

Stan iteracji

Gdy gałąź źródłowa w żądaniu ściągnięcia ulegnie zmianie, zostanie utworzona nowa "iteracja" w celu śledzenia najnowszych zmian. Usługi, które oceniają zmiany kodu, będą chciały opublikować nowy stan w każdej iteracji żądania ściągnięcia. Delegowanie stanu do określonej iteracji żądania ściągnięcia gwarantuje, że stan ma zastosowanie tylko do kodu, który został oceniony i żaden z przyszłych aktualizacji.

Uwaga

Jeśli tworzone żądanie ściągnięcia zawiera ponad 100 000 zmodyfikowanych plików, to ze względu na wydajność i stabilność żądanie ściągnięcia nie będzie obsługiwać iteracji. Oznacza to, że wszelkie dodatkowe zmiany w takim żądaniu ściągnięcia zostaną uwzględnione, ale nie zostanie utworzona nowa iteracja dla tej zmiany. Ponadto każda próba utworzenia stanu dla nieistniejącej iteracji zwróci błąd.

Z drugiej strony, jeśli opublikowany stan ma zastosowanie do całego żądania ściągnięcia, niezależnie od kodu, delegowanie do iteracji może być niepotrzebne. Na przykład sprawdzenie, czy autor (niezmienna właściwość żądania ściągnięcia) należy do określonej grupy, musi zostać oceniony tylko raz, a stan iteracji nie będzie potrzebny.

Podczas konfigurowania zasad stanu, jeśli jest używany stan iteracji, warunki resetowania powinny być ustawione na Resetuj stan za każdym razem, gdy pojawią się nowe zmiany. Dodatkowo gwarantuje to, że żądanie ściągnięcia nie będzie mogło zostać scalone, dopóki najnowsza iteracja nie będzie mieć stanu succeeded.

Zobacz przykłady interfejsu API REST dotyczące publikowania stanu iteracji i żądania ściągnięcia.

Zasady stanu

Korzystając z samego stanu, szczegółowe informacje z usługi zewnętrznej mogą być udostępniane użytkownikom w środowisku żądania ściągnięcia. Czasami udostępnianie informacji o żądaniu ściągnięcia jest niezbędne, ale w innych przypadkach żądania ściągnięcia powinny zostać zablokowane do momentu spełnienia wymagań. Podobnie jak w przypadku zasad wbudowanych, zasady stanu umożliwiają usługom zewnętrznym blokowanie ukończenia żądania ściągnięcia do momentu spełnienia wymagań. Jeśli wymagane są zasady, należy przekazać je w celu ukończenia żądania ściągnięcia. Jeśli zasady są opcjonalne, są tylko informacyjne, a stan succeeded nie jest wymagany w celu ukończenia żądania ściągnięcia.

Zasady stanu są konfigurowane tak samo jak inne zasady gałęzi. Podczas dodawania nowych zasad stanu należy wprowadzić nazwę i gatunek zasad stanu. Jeśli stan został wcześniej opublikowany, możesz wybrać go z listy; Jeśli są to nowe zasady, możesz wpisać nazwę zasad w nazwie gatunku/formatu.

Po określeniu zasad stanu wymagane jest, aby w celu przekazania tych zasad stan succeeded z context pasującą wybraną nazwą był obecny.

Można również wybrać konto autoryzowane , aby wymagać, aby określone konto ma uprawnienia do publikowania stanu, który zatwierdzi zasady.

Możliwość stosowania zasad

Opcje stosowania zasad określają, czy te zasady mają zastosowanie zaraz po utworzeniu żądania ściągnięcia, czy też zasady mają zastosowanie tylko po opublikowaniu pierwszego stanu w żądaniu ściągnięcia.

1. Zastosuj domyślnie — zasady są stosowane natychmiast po utworzeniu żądania ściągnięcia. Dzięki tej opcji zasady nie są przekazywane po utworzeniu żądania ściągnięcia do momentu opublikowania succeeded stanu. Żądanie ściągnięcia można oznaczyć jako wykluczone z zasad, publikując stan notApplicable, co spowoduje usunięcie wymagania dotyczącego zasad.

2. Warunkowe — zasady nie mają zastosowania do momentu opublikowania pierwszego stanu w żądaniu ściągnięcia.

Razem te opcje mogą służyć do tworzenia zestawu zasad dynamicznych. Zasady "aranżacji" najwyższego poziomu można ustawić tak, aby były stosowane domyślnie, podczas gdy żądanie ściągnięcia jest oceniane dla odpowiednich zasad. Następnie, ponieważ dodatkowe zasady warunkowe są określane do zastosowania (być może na podstawie określonych danych wyjściowych kompilacji), stan można opublikować, aby były wymagane. Te zasady aranżacji można oznaczyć succeeded po zakończeniu oceny lub można je oznaczyć notApplicable , aby wskazać żądanie ściągnięcia, że zasady nie mają zastosowania.

Akcje niestandardowe

Oprócz wstępnie zdefiniowanych zdarzeń punktu zaczepienia usługi, które mogą wyzwalać usługę w celu zaktualizowania stanu żądania ściągnięcia, można rozszerzyć menu stanu przy użyciu rozszerzeń usługi Azure DevOps Services w celu nadania akcji wyzwalacza użytkownikowi końcowemu. Jeśli na przykład stan odpowiada przebiegowi testowemu, który może zostać uruchomiony ponownie przez użytkownika końcowego, można uruchomić element menu Uruchom ponownie w menu stanu, który wyzwoli testy do uruchomienia. Aby dodać menu stanu, musisz użyć modelu współtworzenia. Aby uzyskać więcej informacji, zobacz przykład rozszerzenia Usługi Azure DevOps.

Następne kroki

Dowiedz się więcej o interfejsie API stanu żądania ściągnięcia i zapoznaj się z przewodnikami z instrukcjami:

• Tworzenie serwera stanu żądania ściągnięcia za pomocą Node.js
• Tworzenie niestandardowych zasad rozgałęziania za pomocą usługi Azure Functions
• Konfigurowanie zasad rozgałęziania dla usługi zewnętrznej