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

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

Las PR 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 PR mediante el establecimiento de requisitos que se deben cumplir 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 que realizar en el código. Para cubrir estas necesidades individuales y personalizadas, Azure Repos ofrece estados de PR. Los estados de PR se integran en el flujo de trabajo de PR y permiten que los servicios externos cierren sesión mediante programación en un cambio de código al asociar la información de tipo de éxito o error simple con una PR. Opcionalmente, las PR 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 PR: proporciona una manera de que los servicios asocien información de éxito o error con una PR.
• Directiva de estado: proporciona un mecanismo para bloquear la finalización de PR hasta que su estado indique 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 PR y cómo se pueden usar para integrarse en su flujo de trabajo.

Estado de PR

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

• Estado. Uno de estos estados predefinidos: succeeded, failed, pending, notSet, notApplicable o error.
• Descripción. Una cadena que describe el estado para el usuario final.
• Contexto. Un nombre para el estado: normalmente se describe la entidad que lo registra.
• Dirección URL. Un 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 la que un usuario o servicio publica su evaluación sobre una PR y proporciona la respuesta a preguntas como estas:

• ¿Los cambios cumplieron los requisitos?
• ¿Dónde puedo aprender más 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 PR, 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 a 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 PR:

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

Estado Actualizando

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

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

Estado de la iteración

Cuando cambia la rama de origen de una PR, se crea una "iteración" nueva para realizar el seguimiento de los cambios más recientes. Los servicios que evalúan los cambios de código querrán publicar el estado nuevo en cada iteración de una PR. 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ó, no a ninguna de las actualizaciones futuras.

Nota:

Si la PR contiene más de 100 000 archivos modificados, por motivos de rendimiento y estabilidad, esa solicitud de incorporación de cambios no admitirá iteraciones. Esto significa que se incluirá cualquier cambio adicional en dicha PR, pero no se creará ninguna iteración nueva para ese cambio. Además, cualquier intento de crear un estado para una iteración inexistente devolverá un error.

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 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, Restablecer las condiciones debe establecerse en Restablecer el estado cada vez que haya nuevos cambios. Esto garantiza aún más que la PR no se pueda combinar hasta que la iteración más reciente tenga el estado succeeded.

Consulte los ejemplos de la API de REST para publicar el estado en una iteración y en una PR.

Directiva de estado

Solo con el estado, se pueden proporcionar detalles de un servicio externo a los usuarios dentro de la experiencia de PR. A veces, compartir información sobre una PR es lo único que hace falta, pero en otros casos se debe bloquear la combinación de las PR 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 PR hasta que se cumplan los requisitos. Si la directiva se requiere, debe pasar para completar la PR. Si la directiva es opcional, solo es informativo y no se requiere un estado de succeeded para completar la PR.

Las directivas de estado se configuran igual que otras directivas de rama. Al agregar una directiva de estado nueva, 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 se trata de una directiva nueva, puede escribir su nombre en el formato género/nombre.

Cuando se especifica una directiva de estado, requiere que esté presente un estado de succeeded mientras el context coincida con el 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 las directivas

Las opciones de Aplicabilidad de la directiva determinan si esta se aplica tan pronto como se crea una PR o si se aplica solo después de que se publique el primer estado en la PR.

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

2. Condicional: la directiva no se aplica hasta que se publique el primer estado en la PR.

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 PR para las directivas aplicables. Después, según se determina que se apliquen directivas condicionales adicionales (quizás en función de la salida de compilación específica), el estado se puede publicar para que sean necesarias. Esta directiva de orquestación podría marcarse succeeded cuando termine de evaluarse o notApplicable para indicar a la PR 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 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 serie de pruebas 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 PR con Node.js
• Usar Azure Functions para crear directivas de rama personalizadas
• Configurar una directiva de rama para un servicio externo