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

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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 endereçar essas necessidades individuais e personalizadas, Azure Repos oferece o status de solicitação de pull. 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.

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

• Status da solicitação de pull – fornece uma maneira de os serviços associarem informações de êxito/falha a uma solicitação de pull.
• 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 da solicitação de pull e como eles podem ser usados para integrar no 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 AP Ide Status. Um status consiste em quatro partes principais de dados:

• 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 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?

Vamos examinar 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 no modo de exibição Detalhes de PR:

• 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).
• description é mostrado ao lado do ícone e context está disponível em uma 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 um status de PR para uma única PR postando status adicionais, apenas o mais recente dos quais é mostrado para cada exclusivo context. 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:

• “Compilação enfileirada”
• “Compilação em andamento”
• “Build bem-sucedido”

“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.

Observação

Se a PR que está sendo criada contiver mais de 100.000 arquivos modificados, então, por motivos de desempenho e estabilidade, essa PR não oferecerá suporte a iterações. Isso significa que qualquer alteração adicional para essa PR 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 aplicar a toda a PR, independentemente do código, a postagem na iteração poderá ser desnecessária. 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 poderá 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 in-box, a Política de Status fornece uma maneira de os serviços externos bloquearem a conclusão de PR até que os requisitos sejam atendidos. Se a política for necessária, ela deverá ser passada para concluir a solicitação de pull. Se a política for opcional, ela será somente informativa e um status succeeded não será necessário para concluir a solicitação de pull.

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 gênero/nome.

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

Aplicabilidade de política

As opções deaplicabilidade de Política determinam se essa política se aplica assim que uma solicitação de pull é criada ou se a política se aplica somente depois que o primeiro status é postado 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 da solicitação de pull até que um status succeeded seja postado. 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 por padrão enquanto a PR 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 build 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 à 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 modelode 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 de pull com o Node.js
• Usar o Azure Functions para criar políticas de ramificação personalizadas
• Configurar uma política de ramificação para um serviço externo