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 2022 - Azure DevOps Server 2019

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

Categoria	Requerimentos
Acesso ao projeto	Membro de um projeto .
Permissões	- Ver código em projetos privados: Acesso pelo menos Básico. - Clone ou contribua para o código em projetos privados: Membro do grupo de segurança Contributors ou permissões correspondentes no projeto. - Definir permissões de ramo ou repositório: Gerir permissões para o ramo ou repositório. - Alterar ramificação padrão: Editar políticas e permissões para o repositório. - Importar um repositório: Membro do grupo de segurança Administradores de Projeto ou com permissão de Criar repositório ao nível do projeto Git definida como Permitir. Para obter mais informações, consulte Definir permissões do repositório Git.
Serviços	Repos ativado.
Ferramentas	Opcional. Utilize os comandos az repos: Azure DevOps CLI.

Observação

Em projetos públicos, os usuários com acesso Partes Interessadas têm acesso total aos repositórios do Azure, incluindo visualização, clonagem e contribuição para o código.

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 um status de RP para um único RP publicando status adicionais, apenas o mais recente dos quais é mostrado para cada contextexclusivo. 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. 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.

Observação

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, a de condições de Redefinição de deverá ser definida como Status de Redefinição sempre que houver novas 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 de 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 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 publicando um status de notApplicable, o que removerá o requisito da polí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 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