Personalización y ampliación de flujos de trabajo de solicitud de extracción con estado de solicitud de extracción

Azure Repos | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

Las solicitudes de extracción son una excelente herramienta para facilitar las revisiones de código y administrar el movimiento de código dentro de un repositorio. Las directivas de rama aplican la calidad del código durante el proceso de solicitud de extracción estableciendo los requisitos que se deben realizar para cada cambio de código. Estas directivas permiten a los equipos aplicar muchos procedimientos recomendados relacionados con la revisión del código y la ejecución de compilaciones automatizadas, pero muchos equipos tienen requisitos y validaciones adicionales para realizar en el código. Para cubrir estas necesidades individuales y personalizadas, Azure Repos estados de solicitud de extracción. Los estados de las solicitudes de extracción se integran en el flujo de trabajo de solicitud de cambios y permiten que los servicios externos firmen mediante programación un cambio de código mediante la asociación de información de tipo de error o éxito simple a una solicitud de extracción. Opcionalmente, las solicitudes de extracción se pueden bloquear hasta que el servicio externo apruebe el cambio.

La integración en el flujo de trabajo de pr implica algunos conceptos diferentes:

• Estado de la solicitud de extracción: proporciona una manera de que los servicios asocien información de éxito o error a una solicitud de extracción.
• Directiva de estado: proporciona un mecanismo para bloquear la finalización de la solicitud de extracción hasta que el estado de la solicitud de extracción indique que se ha completado correctamente.
• Acciones personalizadas: proporciona una manera de ampliar el menú de estado mediante Azure DevOps Services extensiones.

En este tema, aprenderá sobre los estados de las solicitudes de extracción y cómo se pueden usar para integrarlos en el flujo de trabajo de la solicitud de cambio.

Estado de la solicitud de extracción

El estado de la solicitud de extracción proporciona una manera de que los servicios asocien información de tipo de operación correcta o de error simple a una solicitud de extracción mediante la API de estado. Un estado consta de cuatro partes clave de datos:

• Estado. Uno de los siguientes estados predefinidos: succeeded , , , , o failedpendingnotSetnotApplicableerror .
• Descripción. Cadena que describe el estado del usuario final.
• Contexto. Un nombre para el estado: normalmente describe la entidad que publica el estado.
• Dirección URL. Vínculo en el que los usuarios pueden obtener más información específica del estado.

Básicamente, el estado es la manera en que un usuario o servicio publica su evaluación sobre una solicitud de extracción y proporciona la respuesta a preguntas como:

• ¿Los cambios cumplen los requisitos?
• ¿Dónde puedo obtener más información sobre lo que tengo que hacer para cumplir los requisitos?

Veamos un ejemplo. Considere un servicio de CI necesario para compilar todos los cambios de código en un proyecto. Cuando ese servicio evalúa los cambios en una solicitud de extracción, debe devolver los resultados de la compilación y las pruebas. En el caso de los cambios que pasan la compilación, se podría publicar un estado como este en la pr.

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

Este estado se mostraría al usuario final en la vista Detalles de la pr.

• se muestra al usuario mediante un icono (marca de verificación verde para , X rojo para state , un reloj para y un rojo succeededfailedpending ! para error ).
• se description muestra junto al icono y está disponible en una información sobre context herramientas.
• Cuando se targetUrl aplica , la descripción se representará como un vínculo a la dirección URL.

Estado Actualizando

Un servicio puede actualizar el estado de una pr para una única PR mediante la publicación de estados adicionales, solo el más reciente de los cuales se muestra para cada único context . Publicar varios estados ayuda a los usuarios a administrar las expectativas. Por ejemplo, publicar un estado es una buena manera de confirmar al usuario que un sistema ha recibido un pending evento y está empezando a trabajar. El uso de información como los ejemplos siguientes puede ayudar aún más al usuario a comprender description cómo funciona el sistema:

• "Compilación en cola"
• "Compilación en curso"
• "Compilación correcta"

Estado de iteración

Cuando la rama de origen de una pr. cambia, se crea una nueva "iteración" para realizar el seguimiento de los cambios más recientes. Los servicios que evalúan los cambios de código querrán publicar un nuevo estado en cada iteración de una solicitud de cambio. La publicación del estado en una iteración específica de una pr. garantiza que el estado solo se aplica al código que se evaluó y ninguna de las actualizaciones futuras.

Por el contrario, si el estado publicado se aplica a toda la PR, independientemente del código, la publicación en la iteración puede ser innecesaria. Por ejemplo, comprobar que el autor (una propiedad de PR inmutable) pertenece a un grupo específico solo tendría que evaluarse una vez y el estado de iteración no sería necesario.

Al configurar la directiva de estado, si se usa el estado de iteración, las condiciones de restablecimiento deben establecerse en Restablecer estado siempre que haya nuevos cambios. Esto garantiza además que la pr no se podrá combinar hasta que la iteración más reciente tenga un estado de succeeded .

Consulte los ejemplos de api rest para publicar el estado en una iteración y en una solicitud de extracción.

Directiva de estado

Solo con el estado, los detalles de un servicio externo se pueden proporcionar a los usuarios dentro de la experiencia de la pr. A veces, el uso compartido de información sobre una pr es todo lo necesario, pero en otros casos se debe bloquear la combinación de pr hasta que se cumplen los requisitos. Al igual que las directivas de entrada, la directiva de estado proporciona una manera de que los servicios externos bloqueen la finalización de la PR hasta que se cumplen los requisitos. Si la directiva es necesaria, debe pasarse para completar la solicitud de extracción. Si la directiva es opcional, solo es informativo y no se requiere un estado de para succeeded completar la solicitud de extracción.

Las directivas de estado se configuran igual que otras directivas de rama. Al agregar una nueva directiva de estado, se deben especificar el nombre y el género de la directiva de estado. Si el estado se ha publicado anteriormente, puede seleccionarlo de la lista. si se trata de una nueva directiva, puede escribir el nombre de la directiva en el nombre de génerode formato.

Cuando se especifica una directiva de estado, requiere que un estado de con el nombre seleccionado correspondiente esté presente en para que esta succeededcontext directiva se pase.

También se puede seleccionar una cuenta autorizada para requerir que una cuenta específica tenga la autoridad para publicar el estado que aprobará la directiva.

Aplicabilidad de las directivas

Las opciones de aplicabilidad de directiva determinan si esta directiva se aplica en cuanto se crea una solicitud de extracción o si la directiva se aplica solo después de que el primer estado se publique en la solicitud de extracción.

1. Aplicar de forma predeterminada: la directiva se aplica en cuanto se crea la solicitud de extracción. Con esta opción, la directiva no pasa después de la creación de la solicitud de extracción hasta que succeeded se publica un estado. Una PR se puede marcar como exenta de la directiva mediante la publicación de un estado de notApplicable , lo que quitará el requisito de directiva.

2. Condicional: la directiva no se aplica hasta que el primer estado se publica en la solicitud de extracción.

Juntas, estas opciones se pueden usar para crear un conjunto de directivas dinámicas. Se podría establecer una directiva de "orquestación" de nivel superior para que se aplique de forma predeterminada mientras se evalúa la solicitud de cambio para las directivas aplicables. A continuación, a medida que se determina que se aplican directivas condicionales adicionales (quizás en función de la salida de compilación específica), se puede publicar el estado para que sea necesario. Esta directiva de orquestación podría marcarse cuando haya terminado de evaluarse o se podría marcar para indicar a la solicitud de cambio que la directiva succeedednotApplicable no se aplica.

Acciones personalizadas

Además de los eventos de enlace de servicio predefinidos que pueden desencadenar el servicio para actualizar el estado de la pr, es posible ampliar el menú de estado mediante extensiones de Azure DevOps Services para proporcionar acciones de desencadenador al usuario final. Por ejemplo, si el estado corresponde a una ejecución de prueba que el usuario final puede reiniciar, es posible tener un elemento de menú Reiniciar en el menú de estado que desencadenaría la ejecución de pruebas. Para agregar un menú de estado, deberá usar el modelo de contribución. Consulte el ejemplo de la guía de contribuciones en GitHub, donde puede ver las partes del código que agregan los siguientes elementos de ejemplo al menú de estado.

Pasos siguientes

Obtenga más información sobre pr Status API y consulte las guías paso a paso:

• Cree un servidor de estado de solicitud de extracción con Node.js
• Usar Azure Functions para crear directivas de rama personalizadas
• Configuración de una directiva de rama para un servicio externo