Personalización y ampliación de flujos de trabajo de solicitud de incorporación de cambios con el estado de la solicitud de incorporación de cambios

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

Las solicitudes de incorporación de cambios 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 incorporación de cambios mediante el establecimiento de 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 ofrece estados de solicitud de incorporación de cambios. Los estados de solicitud de incorporación de cambios se integran en el flujo de trabajo de solicitud de incorporación de cambios y permiten que los servicios externos cierren sesión mediante programación en un cambio de código asociando información de tipo de éxito o error simple con una solicitud de incorporación de cambios. Opcionalmente, las solicitudes de incorporación de cambios se pueden bloquear hasta que el servicio externo apruebe el cambio.

Prerrequisitos

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

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

En este tema, obtendrá información sobre los estados de las solicitudes de incorporación de cambios y cómo se pueden usar para integrarse en el flujo de trabajo de pr.

Estado de la solicitud de incorporación de cambios

El estado de la solicitud de incorporación de cambios proporciona una manera de que los servicios asocien información de tipo de éxito o error simple con una solicitud de incorporación de cambios mediante la API de estado. Un estado consta de cuatro fragmentos clave de datos:

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

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

• ¿Los cambios cumplen los requisitos?
• ¿Dónde puedo obtener más información sobre lo que necesito 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 incorporación de cambios, debe publicar los resultados de la compilación y las pruebas. En el caso de los cambios que pasan la compilación, podría publicarse un estado similar al siguiente en la solicitud de incorporación de cambios:

{
    "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 solicitud de incorporación de cambios:

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

Estado de actualización

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

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

Estado de iteración

Cuando cambia la rama de origen de una solicitud de incorporación de cambios, 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 el nuevo estado en cada iteración de una solicitud de incorporación de cambios. La publicación del estado en una iteración específica de una solicitud de incorporación de cambios 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 solicitud de incorporación de cambios, independientemente del código, la publicación en la iteración puede ser innecesaria. Por ejemplo, comprobar que el autor (una propiedad pr inmutable) pertenece a un grupo específico solo tendría que evaluarse una vez y no sería necesario el estado de iteración.

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 cambios nuevos. Esto garantiza aún más que la solicitud de incorporación de cambios 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 incorporación de cambios.

Directiva de estado

Con el estado solo, se pueden proporcionar detalles de un servicio externo a los usuarios dentro de la experiencia de solicitud de incorporación de cambios. A veces, compartir información sobre una solicitud de incorporación de cambios es todo lo necesario, pero en otros casos se debe bloquear la combinación de solicitudes de incorporación de cambios hasta que se cumplan los requisitos. Al igual que las directivas integradas, la directiva de estado proporciona una manera de que los servicios externos bloqueen la finalización de solicitudes de incorporación de cambios hasta que se cumplan los requisitos. Si se requiere la directiva, debe pasar para completar la solicitud de incorporación de cambios. Si la directiva es opcional, solo es informativo y no se requiere un estado de para completar la solicitud de incorporación de succeeded cambios.

Las directivas de estado se configuran igual que otras directivas de rama. Al agregar una nueva directiva de estado, se debe escribir el nombre y el género de la directiva de estado. Si el estado se ha publicado anteriormente, puede elegirlo de la lista; si es una nueva directiva, puede escribir el nombre de la directiva en elnombre del / de formato.

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

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

Aplicabilidad de directivas

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

1. Aplicar de forma predeterminada : la directiva se aplica en cuanto se crea la solicitud de incorporación de cambios. Con esta opción, la directiva no pasa después de la creación de la solicitud de incorporación de cambios hasta que se publique un succeeded estado. Una solicitud de incorporación de cambios se puede marcar exenta de la directiva publicando un estado de , lo que quitará el requisito de notApplicabledirectiva.

2. Condicional : la directiva no se aplica hasta que se publique el primer estado en la solicitud de incorporación de cambios.

Juntas, estas opciones se pueden usar para crear un conjunto de directivas dinámicas. Una directiva de "orquestación" de nivel superior podría establecerse para que se aplique de forma predeterminada mientras se evalúa la solicitud de incorporación de cambios para las directivas aplicables. A continuación, a medida que se determinan directivas condicionales adicionales que se aplican (quizás en función de la salida de compilación específica), el estado se puede publicar para que sean necesarios. Esta directiva de orquestación podría marcarse succeeded cuando termine de evaluarse o se podría marcar notApplicable para indicar a la solicitud de incorporación de cambios que la directiva 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 solicitud de incorporación de cambios, 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 pruebas para ejecutarse. Para agregar un menú de estado, deberá usar el modelo de contribución. Para más información, consulte el ejemplo de extensión de Azure DevOps.

Pasos siguientes

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

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