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

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

Pull requests 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 garantem a qualidade do código durante o processo de pull request, estabelecendo requisitos que devem ser cumpridos em 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 estas necessidades individuais e personalizadas, o Azure Repos oferece estados de pull request. 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.

Pré-requisitos

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

• Pull request status - fornece uma forma para os serviços associarem informações de sucesso/falha a um pull request.
• Política de status - fornece um mecanismo para bloquear a conclusão do pull request até que o status do pull request 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, irá aprender sobre os status de pedidos de pull e como eles podem ser usados para se integrarem no fluxo de trabalho de PR.

Status da solicitação pull

O estado do pull request fornece uma forma para os serviços associarem informações básicas sobre sucesso ou falha a um pull request, usando a API de estado . Um status consiste em quatro dados principais:

• Estado. Um dos seguintes estados predefinidos: succeeded, failed, pending, notSet, notApplicableou 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?

Vejamos um exemplo. Considere um serviço de CI que é 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 pendinge um vermelho ! para error).
• O description é exibido ao lado do ícone e o context está disponível em uma dica de ferramenta.
• Quando um targetUrl é aplicado, a descrição será processada como um link para a URL.

Estado de atualização

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

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

Status da iteração

Quando a ramificação de origem em um PR muda, uma nova "iteração" é criada para acompanhar 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. A atualização de estado numa iteração específica de um PR garante que o estado se aplique apenas ao código que foi avaliado e não a qualquer das atualizações futuras.

Por outro lado, se o status publicado se aplica a todo o PR, independentemente do código, a publicação na iteração pode ser desnecessária. 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 alterações. Isto também garante que o PR não poderá ser integrado até que a última iteração tenha um status de succeeded.

Consulte os exemplos da API REST para publicar o estado numa iteração e num pull request.

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. Assim como as políticas na caixa, a política de status fornece uma maneira para que serviços externos bloqueiem a conclusão de PR até que os requisitos sejam atendidos. Se a política for necessária, deve ser aprovada para concluir o pedido de pull. Se a política for opcional, ela será apenas informativa e um status de succeeded não será necessário para concluir o pull request.

As políticas de status são configuradas da mesma forma que outras políticas de ramificação . 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 gênero/nome.

Quando uma política de status é especificada, ela requer que um status de succeeded com o context correspondente ao nome selecionado 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 um estado que aprovará a política.

Aplicabilidade das políticas

As opções aplicabilidade da Política determinam se esta política se aplica assim que um pedido pull é criado ou se a política se aplica apenas depois que o primeiro estado é publicado no pedido pull.

1. Aplicar por padrão - A política se aplica assim que a solicitação pull é criada. Com esta opção, a política não é aprovada após a criação do pull request até que um status de succeeded seja publicado. Um RP pode ser marcado como isento da política ao publicar um status de notApplicable, removendo o requisito da política.

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

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 PR está a ser avaliada para as políticas aplicáveis. Em seguida, à medida que políticas condicionais adicionais são definidas para serem aplicadas (talvez com base na saída de compilação específica), o estado pode ser atualizado para torná-las obrigatórias. Esta política de orquestração pode ser marcada como succeeded quando terminar a avaliação ou como notApplicable para indicar ao PR 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 extensões dos Serviços de DevOps do Azure para fornecer ações de gatilho ao usuário final. Por exemplo, se o estado corresponder a uma execução de teste que pode ser reiniciada pelo utilizador final, é possível ter um item de menu Reiniciar no menu de estado que iniciaria a execução dos 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 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 estado de pull request com Node.js
• Utilizar Funções do Azure para criar políticas de ramificação personalizadas
• Configurar uma política de filial para um serviço externo