Dostosowywanie i rozszerzanie przepływów pracy pull requestów przy użyciu statusu pull requestów

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

Pull requesty to doskonałe narzędzie ułatwiające przeglądy kodu i zarządzanie przenoszeniem kodu w repozytorium. Polityki gałęzi dbają o jakość kodu podczas procesu zgłaszania żądań łączenia, ustanawiając wymogi, które muszą być spełnione przy każdej zmianie 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 indywidualne i niestandardowe potrzeby, Azure Repos oferuje statusy dla pull requestów. Statusy żądań ściągnięcia integrują się z przepływem pracy PR, umożliwiając usługom zewnętrznym zautoryzowanie zmiany kodu poprzez dodanie prostych informacji o powodzeniu/niepowodzeniu do żądania ściągnięcia. Opcjonalnie żądania ściągnięcia mogą być blokowane do momentu zatwierdzenia zmiany przez usługę zewnętrzną.

Wymagania wstępne

Kategoria	Wymagania
Dostęp do projektu	Członek projektu .
uprawnienia	— Wyświetlanie kodu w projektach prywatnych: co najmniej dostęp na poziomie Podstawowym. — Klonowanie lub współtworzenie kodu w prywatnych projektach: członkostwo w grupie zabezpieczeń Współautorzy lub odpowiednie uprawnienia w projekcie. — Ustaw uprawnienia gałęzi lub repozytorium: Zarządzanie uprawnieniami dla gałęzi lub repozytorium. - Zmień gałąź domyślną: Edytuj zasady uprawnienia dla repozytorium. — Zaimportuj repozytorium: członek grupy zabezpieczeń Administratorzy projektów lub uprawnienia na poziomie projektu Git Utwórz repozytorium ustawione na Dozwolone. Aby uzyskać więcej informacji, zobacz Ustawianie uprawnień repozytorium Git.
Usługi	Repozytoria włączone.
Narzędzia	Opcjonalny. Użyj poleceń az repos: Azure DevOps CLI.

Uwaga

W projektach publicznych użytkownicy z dostępem Stakeholder mają pełny dostęp do usługi Azure Repos, w tym wyświetlanie, klonowanie i współtworzenie kodu.

Integracja z przepływem pracy pull requestów obejmuje kilka różnych pojęć:

• Status pull requestu — umożliwia usłudze kojarzenie informacji o sukcesie lub porażce z pull requestem.
• Zasady statusu — zapewniają mechanizm blokowania ukończenia pull requestu, dopóki jego status nie wskazuje powodzenia.
• akcje niestandardowe — umożliwia rozszerzenie menu stanu przy użyciu rozszerzeń usługi Azure DevOps Services.

W tym temacie dowiesz się więcej o statusach żądań ściągnięcia i ich użyciu w integracji z przepływem pracy PR.

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, failed, pending, 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 publikują ocenę pull requestu i dostarczają odpowiedzi na pytania, takie jak:

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

Przyjrzyjmy się przykładowi. Rozważ usługę ciągłej integracji , która jest wymagana do kompilowania wszystkich zmian kodu w projekcie. Gdy usługa ocenia zmiany w pull requestu, musi zamieścić z powrotem wyniki kompilacji i testów. W przypadku zmian, które przechodzą pomyślnie kompilację, status podobny do poniższego może zostać opublikowany w pull request:

{
    "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 w widoku Szczegóły pull requesta:

• state jest wyświetlany użytkownikowi za pomocą ikony (zielony znacznik wyboru dla succeeded, czerwony X dla failed, zegar dla pendingi czerwony ! dla error).
• description jest wyświetlany obok ikony, a context jest dostępna w etykietce narzędzia.
• Po zastosowaniu targetUrl opis będzie renderowany jako link do adresu URL.

Aktualizowanie stanu

Usługa może zaktualizować stan żądania ściągnięcia dla pojedynczego PR, publikując dodatkowe stany, przy czym tylko najnowsze są wyświetlane dla każdego unikatowego context. Publikowanie wielu statusów pomaga użytkownikom zarządzać oczekiwaniami. Na przykład opublikowanie stanu pending jest dobrym sposobem potwierdzenia użytkownikowi, że system otrzymał zdarzenie i rozpoczyna pracę. Użycie informacyjnego description, takiego jak poniższe przykłady, może dodatkowo pomóc użytkownikowi zrozumieć, jak działa system.

• "Kompilacja w kolejce"
• Budowa 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 status przy każdej iteracji Pull Request. Delegowanie stanu do określonej iteracji żądania ściągnięcia gwarantuje, że dotyczy tylko kodu, który został oceniony, i żadnych 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 w związku z tą zmianą. Ponadto każda próba stworzenia stanu dla iteracji, która nie istnieje, zakończy się błędem.

Z drugiej strony, jeśli opublikowany stan ma zastosowanie do całego PR, niezależnie od kodu, publikowanie w 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, należy ocenić tylko raz, a status iteracji nie będzie potrzebny.

Podczas konfigurowania zasad stanu, jeśli używany jest stan iteracji, warunki resetowania należy ustawić na Resetuj status, gdy tylko nastąpią nowe zmiany. To dodatkowo gwarantuje, że pull request nie będzie mógł zostać scalony, dopóki najnowsza iteracja nie będzie mieć stanu succeeded.

Zobacz przykłady interfejsu API REST dotyczące umieszczania stanu na iteracji oraz na wniosku o zaciągnięcie.

Polityka statusu

Wykorzystując sam status, można udostępniać szczegółowe informacje z usługi zewnętrznej użytkownikom w obsłudze pull request. Czasami udostępnianie informacji o PR jest wystarczające, ale w innych przypadkach PR powinny zostać zablokowane aż do spełnienia wymagań. Podobnie jak w przypadku zasad domyślnych, polityka statusu umożliwia usługom zewnętrznym blokowanie zakończenia żądania ściągnięcia do momentu spełnienia wymagań. Jeśli wymagana jest polityka, musi zostać zatwierdzona, aby zakończyć pull request. Jeśli zasada jest opcjonalna, ma tylko charakter informacyjny, a stan succeeded nie jest wymagany w celu ukończenia żądania ściągnięcia.

Polityki stanu są konfigurowane tak samo jak inne polityki gałęzi . Podczas dodawania nowych zasad statusu należy wprowadzić nazwę i typ zasad statusu. Jeśli status został wcześniej opublikowany, możesz go wybrać z listy; jeśli to nowa polityka, możesz wpisać nazwę polityki w formacie gatunek/nazwa.

Aby te zasady mogły zostać zaakceptowane, po określeniu polityki statusu wymaga się obecności stanu succeeded z context pasującym do wybranej nazwy.

Można również wybrać autoryzowane konto, aby wymagać, aby określone konto miało uprawnienia do publikowania postu stanowiącego zatwierdzenie polityki.

Możliwość stosowania zasad

Opcje stosowania zasad określają, czy te zasady mają zastosowanie natychmiast po utworzeniu pull requestu, czy też dopiero po opublikowaniu pierwszego statusu w pull requeście.

1. Zastosuj domyślnie — zasady są stosowane natychmiast po utworzeniu żądania ściągnięcia. W przypadku tej opcji polityka nie przechodzi po utworzeniu żądania ściągnięcia, dopóki nie zostanie opublikowany stan succeeded. Pull request można oznaczyć jako zwolniony z polityki, publikując status notApplicable, co spowoduje usunięcie wymogu polityki.

2. Warunkowe — polityka nie ma zastosowania do momentu opublikowania pierwszego stanu w pull requestu.

Razem te opcje mogą służyć do tworzenia zestawu zasad dynamicznych. Zasady "orkiestracji" najwyższego poziomu można ustawić tak, aby były stosowane domyślnie, podczas gdy żądanie ściągnięcia jest oceniane pod kątem odpowiednich zasad. Następnie, gdy dodatkowe zasady warunkowe są ustalane do wdrożenia (być może na podstawie określonych danych wyjściowych kompilacji), można opublikować ich status, aby stały się wymagane. Można oznaczyć tę politykę orkiestracji jako succeeded po zakończeniu oceny lub jako notApplicable, aby wskazać PR, że polityka nie ma zastosowania.

Akcje niestandardowe

Oprócz wstępnie zdefiniowanych zdarzeń punktu zaczepienia usługi, które mogą wyzwolić usługę w celu zaktualizowania stanu PR, można rozszerzyć menu statusu przy użyciu rozszerzeń Azure DevOps Services w celu dodania akcji wyzwalającej 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żliwe jest dodanie elementu menu Uruchom ponownie do menu stanu, które uruchomi testy. Aby dodać menu stanu, należy użyć modelu współtworzenia. Aby uzyskać więcej informacji, zobacz stronę przykładowego rozszerzenia Azure DevOps .

Następne kroki

Dowiedz się więcej na temat interfejsu API statusu PR i zapoznaj się z przewodnikami:

• Utwórz serwer statusu pull requestu za pomocą Node.js
• Tworzenie niestandardowych zasad rozgałęziania za pomocą usługi Azure Functions
• Konfigurowanie zasad rozgałęziania dla usługi zewnętrznej