Personalize e estenda fluxos de trabalho de solicitação pull com status de pull request

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

As solicitações pull são uma ótima ferramenta para facilitar revisões de código e gerenciar a movimentação de código dentro de um repositório. As políticas de ramificação impõem a qualidade do código durante o processo de solicitação pull, estabelecendo requisitos que devem ser executados para cada alteração de código. Essas políticas permitem que as equipes apliquem muitas práticas recomendadas relacionadas à revisão de código e à execução de compilações automatizadas, mas muitas equipes têm requisitos e validações adicionais para executar no código. Para cobrir essas necessidades individuais e personalizadas, o Azure Repos oferece status de solicitação pull. Os status da solicitação pull integram-se ao fluxo de trabalho de RP e permitem que serviços externos assinem programaticamente uma alteração de código, associando informações simples de tipo de sucesso/falha a uma solicitação pull. Opcionalmente, as solicitações pull podem ser bloqueadas até que o serviço externo aprove a alteração.

A integração no fluxo de trabalho de RP envolve alguns conceitos diferentes:

• Status da solicitação pull - fornece uma maneira para os serviços associarem informações de sucesso/falha a uma solicitação pull.
• Política de status - fornece um mecanismo para bloquear a conclusão da solicitação pull até que o status da solicitação pull indique sucesso.
• Ações personalizadas - fornece uma maneira de estender o menu de status usando as extensões dos Serviços de DevOps do Azure.

Neste tópico, você aprenderá sobre os status de solicitação pull e como eles podem ser usados para integração no fluxo de trabalho de RP.

Status da solicitação pull

O status da solicitação pull fornece uma maneira para os serviços associarem informações simples de tipo de sucesso/falha a uma solicitação pull, usando a API de status. Um status consiste em quatro dados principais:

• Estado. Um dos seguintes estados predefinidos: succeeded, failed, pending, notSet, notApplicable, ou error.
• Descrição. Uma cadeia de caracteres que descreve o status para o usuário final.
• Contexto. Um nome para o status - normalmente descrevendo a entidade que posta o status.
• URL. Um link onde os usuários podem obter mais informações específicas para o status.

Essencialmente, status é a maneira como um usuário ou serviço posta sua avaliação sobre uma solicitação pull e fornece a resposta para perguntas como:

• As alterações cumpriram os requisitos?
• Onde posso saber mais sobre o que preciso fazer para atender aos requisitos?

Vamos ver um exemplo. Considere um serviço de CI necessário para criar todas as alterações de código em um projeto. Quando esse serviço avalia as alterações em uma solicitação pull, ele precisa postar de volta os resultados da compilação e dos testes. Para alterações que passam na compilação, um status como este pode ser postado no PR:

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

Esse status seria exibido para o usuário final na visualização Detalhes de RP:

• O state é mostrado ao usuário usando um ícone (verificação verde para succeeded, X vermelho para failed, um relógio para pending, e um vermelho ! para error).
• O description é exibido ao lado do ícone e o está disponível em uma dica context de ferramenta.
• Quando um targetUrl é aplicado, a descrição será processada como um link para o URL.

Estado de atualização

Um serviço pode atualizar um status de RP para um único RP publicando status adicionais, apenas o mais recente dos quais é mostrado para cada único context. A publicação de vários status ajuda os usuários a gerenciar as expectativas. Por exemplo, postar um pending status é uma boa maneira de reconhecer ao usuário que um sistema recebeu um evento e está começando a funcionar. Usar um informativo description como os exemplos a seguir pode ajudar ainda mais o usuário a entender como o sistema está funcionando:

• "Compilação em fila"
• "Construir em progresso"
• "Construção bem-sucedida"

Status da iteração

Quando a ramificação de origem em uma RP muda, uma nova "iteração" é criada para controlar as alterações mais recentes. Os serviços que avaliam as alterações de código desejarão postar um novo status em cada iteração de um PR. O status de postagem em uma iteração específica de um PR garante que o status se aplique apenas ao código que foi avaliado e nenhuma das atualizações futuras.

Nota

Se o PR que está sendo criado contiver mais de 100.000 arquivos modificados, então, por motivos de desempenho e estabilidade, esse PR não suportará iterações. Isso significa que qualquer alteração adicional a esse RP será incluída, mas nenhuma nova iteração será criada para essa alteração. Além disso, qualquer tentativa de criar um status para uma iteração inexistente retornará um erro.

Por outro lado, se o status postado se aplica a todo o PR, independentemente do código, o lançamento na iteração pode ser desnecessário. Por exemplo, verificar se o autor (uma propriedade PR imutável) pertence a um grupo específico só precisaria ser avaliado uma vez, e o status da iteração não seria necessário.

Ao configurar a política de status, se o status da iteração estiver sendo usado, as condições de Redefinição deverão ser definidas como Redefinir status sempre que houver novas alterações. Isso garante ainda que o PR não poderá ser mesclado até que a última iteração tenha um status de succeeded.

Consulte os exemplos da API REST para postar o status em uma iteração e em uma solicitação pull.

Política de status

Usando apenas o status, os detalhes de um serviço externo podem ser fornecidos aos usuários dentro da experiência de RP. Por vezes, a partilha de informações sobre um RP é tudo o que é necessário, mas noutros casos os PR devem ser impedidos de se fundirem até que os requisitos sejam cumpridos. Como as políticas de caixa de entrada, a política de status fornece uma maneira para serviços externos bloquearem a conclusão de RP até que os requisitos sejam atendidos. Se a política for necessária, ela deve ser aprovada para concluir a solicitação pull. Se a política for opcional, ela será apenas informativa e um status de succeeded não será necessário para concluir a solicitação pull.

As políticas de status são configuradas da mesma forma que outras políticas de filial. Ao adicionar uma nova política de status, o nome e o gênero da política de status devem ser inseridos. Se o status foi postado anteriormente, você pode escolhê-lo na lista; Se for uma nova política, você pode digitar o nome da política no formato Nome do gênero/.

Quando uma política de status é especificada, ela requer que um status de succeeded com o context nome selecionado correspondente esteja presente para que essa política seja aprovada.

Uma conta autorizada também pode ser selecionada para exigir que uma conta específica tenha autoridade para publicar o status que aprovará a política.

Aplicabilidade das políticas

As opções de aplicabilidade da política determinam se essa política se aplica assim que uma solicitação pull é criada ou se a política se aplica somente depois que o primeiro status é postado na solicitação pull.

1. Aplicar por padrão - A política se aplica assim que a solicitação pull é criada. Com essa opção, a política não passa após a criação da solicitação pull até que um succeeded status seja publicado. Um RP pode ser marcado como isento da política publicando um status de , o que removerá o requisito da notApplicablepolítica.

2. Condicional - A política não se aplica até que o primeiro status seja publicado na solicitação pull.

Em conjunto, estas opções podem ser utilizadas para criar um conjunto de políticas dinâmicas. Uma política de "orquestração" de nível superior pode ser definida para ser aplicada por padrão enquanto a RP está sendo avaliada para políticas aplicáveis. Em seguida, à medida que políticas condicionais adicionais são determinadas a serem aplicadas (talvez com base na saída de compilação específica), o status pode ser postado para torná-las necessárias. Essa política de orquestração pode ser marcada succeeded quando terminar de avaliar ou pode ser marcada notApplicable para indicar ao RP que a política não se aplica.

Ações personalizadas

Além dos eventos de gancho de serviço predefinidos que podem acionar o serviço para atualizar o status de RP, é possível estender o menu de status usando as extensões dos Serviços de DevOps do Azure para fornecer ações de gatilho ao usuário final. Por exemplo, se o status corresponder a uma execução de teste que pode ser reiniciada pelo usuário final, é possível ter um item de menu Reiniciar no menu de status que acionaria a execução de testes. Para adicionar um menu de status, você precisará usar o modelo de contribuição. Para obter mais informações, consulte o exemplo de extensão do Azure DevOps.

Próximos passos

Saiba mais sobre a API de status de RP e confira os guias de instruções:

• Criar um servidor de status de solicitação pull com Node.js
• Utilizar Funções do Azure para criar políticas de ramificação personalizadas
• Configurar uma política de ramificação para um serviço externo