Personalizar e estender fluxos de trabalho de solicitação de pull com o status da solicitação de pull

Azure DevOps Services | Servidor Azure DevOps | Azure DevOps Server 2022

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

Pré-requisitos

A integração ao fluxo de trabalho de PR envolve alguns conceitos diferentes:

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

Neste tópico, você aprenderá sobre os status dos pull requests e como eles podem ser usados para integrar-se ao fluxo de trabalho de PR.

Status da solicitação de pull

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

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

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

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

Vejamos 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 de pull, ele precisa postar os resultados do build e dos testes. Para alterações que passam pelo build, um status como esse pode ser postado na 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 de Detalhes do PR:

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

Atualizando o status

Um serviço pode atualizar o status de um PR único ao adicionar novos status, sendo exibido apenas o mais recente para cada context exclusivo. Postar 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á iniciando o trabalho. Usar um informativo description como os seguintes exemplos pode ajudar ainda mais o usuário a entender como o sistema está funcionando:

• Build na fila
• Construção em andamento
• Construção bem-sucedida

Status da iteração

Quando o branch de origem em uma PR é alterado, 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 uma PR. Postar o status em uma iteração específica de uma PR garante que o status se aplique apenas ao código que foi avaliado e nenhuma das atualizações futuras.

Por outro lado, se o status postado se aplicar a toda a PR, independentemente do código, talvez não seja necessário postar na iteração. Por exemplo, verificar se o autor (uma propriedade de 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 a PR não será capaz de ser mesclada até que a iteração mais recente tenha um status de succeeded.

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

Política de status

Usando o status sozinho, os detalhes de um serviço externo podem ser fornecidos aos usuários dentro da experiência de PR. Às vezes, o compartilhamento de informações sobre uma PR é tudo o que é necessário, mas em outros casos as PRs devem ser impedidas de se mesclar até que os requisitos sejam atendidos. Assim como as políticas internas, a política de status fornece uma maneira de os serviços externos impedirem a conclusão do pull request (PR) até que os requisitos sejam cumpridos. Se a política for necessária, ela precisa ser aprovada para concluir o pull request. Se a política for opcional, é apenas informativa e um status de succeeded não é necessário para concluir o pull request.

As políticas de status são configuradas da mesma forma que outras políticas de branch. 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 tiver sido postado anteriormente, você poderá selecioná-lo na lista; se for uma nova política, você poderá digitar o nome da política no formato genre/name.

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

Aplicabilidade da política

As opções de aplicabilidade da política determinam se essa política se aplica imediatamente após a criação de uma solicitação de pull ou apenas depois que o primeiro status é publicado na solicitação de pull.

1. Aplicar por padrão – a política se aplica assim que a solicitação de pull é criada. Com essa opção, a política não passa após a criação do pull request até que um succeeded status seja publicado. Uma PR pode ser marcada como isenta da política postando um status de notApplicable, o que removerá o requisito de política.

2. Condicional – a política não se aplica até que o primeiro status seja postado na solicitação de pull.

Juntas, essas opções podem ser usadas 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 automaticamente enquanto a PR está sendo avaliada em busca de políticas aplicáveis. Em seguida, à medida que políticas condicionais adicionais são determinadas e consideradas para aplicação (talvez com base na saída específica do build), o status pode ser publicado para que se tornem obrigatórias. Essa política de orquestração pode ser marcada succeeded quando terminar de avaliar ou pode ser marcada notApplicable para indicar à PR que a política não se aplica.

Ações personalizadas

Além de eventos predefinidos de gancho de serviço que podem disparar o serviço para atualizar o status de PR, é possível estender o menu de status usando extensões do Azure DevOps Services 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 dispararia testes a serem executados. 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óximas etapas

Saiba mais sobre a API de Status de PR e confira os guias de instruções:

• Criar um servidor de status de solicitação pull com Node.js
• Usar o Azure Functions para criar políticas de ramificação personalizadas
• Configurar uma política de branch para um serviço externo