Personalización de la canalización

Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019

Esta es una guía paso a paso sobre las formas comunes de personalizar la canalización.

Requisito previo

Siga las instrucciones de Creación de la primera canalización para crear una canalización de trabajo.

Comprender el azure-pipelines.yml archivo

Una canalización se define mediante un archivo YAML en el repositorio. Normalmente, este archivo se denomina azure-pipelines.yml y se encuentra en la raíz del repositorio.

• Vaya a la página Pipelines en Azure Pipelines y seleccione la canalización que creó.

• Seleccione Editar en el menú contextual de la canalización para abrir el editor de YAML de la canalización. Examine el contenido del archivo YAML.

    trigger:
    - main
  
    pool:
      vmImage: 'ubuntu-latest'
  
    steps:
    - task: Maven@3
      inputs:
        mavenPomFile: 'pom.xml'
        mavenOptions: '-Xmx3072m'
        javaHomeOption: 'JDKVersion'
        jdkVersionOption: '1.8'
        jdkArchitectureOption: 'x64'
        publishJUnitResults: false
        testResultsFiles: '**/surefire-reports/TEST-*.xml'
        goals: 'package'
  

  Nota

  El contenido del archivo YAML puede ser diferente en función del repositorio de ejemplo con el que empezó o de las actualizaciones realizadas en Azure Pipelines.

Esta canalización se ejecuta siempre que el equipo inserta un cambio en la rama principal del repositorio o crea una solicitud de extracción. Se ejecuta en una máquina Linux hospedada por Microsoft. El proceso de canalización tiene un solo paso, que consiste en ejecutar la tarea maven.

Cambio de la plataforma en la que se basa la compilación

Puede compilar el proyecto en agentes hospedados por Microsoft que ya incluyen SDK y herramientas para varios lenguajes de desarrollo. O bien, puede usar agentes auto hospedados con herramientas específicas que necesite.

• Vaya al editor de la canalización seleccionando Editar acción de canalización en la compilación o seleccionando Editar en la página principal de la canalización.

• Actualmente, la canalización se ejecuta en un agente de Linux:

  pool:
    vmImage: "ubuntu-latest"
  

• Para elegir otra plataforma como Windows o Mac, cambie el vmImage valor:

  pool:
    vmImage: "windows-latest"
  

  pool:
    vmImage: "macos-latest"
  

• Seleccione Guardar y confirme los cambios para ver que la canalización se ejecuta en otra plataforma.

Agregar pasos

Puede agregar más scripts otareas como pasos a la canalización. Una tarea es un script empaquetado previamente. Puede usar tareas para compilar, probar, publicar o implementar la aplicación. Para Java, la tarea maven que usamos controla los resultados de pruebas y publicación; sin embargo, también puede usar una tarea para publicar los resultados de cobertura de código.

• Abra el editor de YAML de la canalización.

• Agregue el siguiente fragmento de código al final del archivo YAML.

  - task: PublishCodeCoverageResults@1
    inputs:
      codeCoverageTool: "JaCoCo"
      summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
      reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
      failIfCoverageEmpty: true
  

• Seleccione Guardar y confirme los cambios.

• Puede ver los resultados de las pruebas y la cobertura de código seleccionando la compilación y yendo a las pestañas Prueba y Cobertura.

Compilación en varias plataformas

Puede compilar y probar el proyecto en varias plataformas. Una manera de hacerlo es con strategy y matrix . Puede usar variables para colocar datos cómodamente en varias partes de una canalización. En este ejemplo, usaremos una variable para pasar el nombre de la imagen que queremos usar.

• En el azure-pipelines.yml archivo, reemplace este contenido:

  pool:
    vmImage: "ubuntu-latest"
  

  con el siguiente contenido:

  strategy:
    matrix:
      linux:
        imageName: "ubuntu-latest"
      mac:
        imageName: "macOS-latest"
      windows:
        imageName: "windows-latest"
    maxParallel: 3
  
  pool:
    vmImage: $(imageName)
  

• Seleccione Guardar y confirme los cambios para ver que la compilación se ejecuta hasta tres trabajos en tres plataformas diferentes.

Cada agente solo puede ejecutar un trabajo a la vez. Para ejecutar varios trabajos en paralelo, debe configurar varios agentes. También necesita suficientes trabajos paralelos.

Compilación con varias versiones

Para compilar un proyecto con diferentes versiones de ese lenguaje, puede usar un de matrix versiones y una variable. En este paso, puede compilar el proyecto de Java con dos versiones diferentes de Java en una sola plataforma o ejecutar versiones diferentes de Java en plataformas diferentes.

• Si desea compilar en una sola plataforma y varias versiones, agregue la siguiente matriz al archivo antes de la tarea Maven y azure-pipelines.yml después de vmImage .

  strategy:
    matrix:
      jdk10:
        jdkVersion: "1.10"
      jdk11:
        jdkVersion: "1.11"
    maxParallel: 2
  

• A continuación, reemplace esta línea en la tarea de Maven:

  jdkVersionOption: "1.11"
  

  por esta otra:

  jdkVersionOption: $(jdkVersion)
  

• Asegúrese de volver a cambiar $(imageName) la variable a la plataforma que prefiera.

• Si desea compilar en varias plataformas y versiones, reemplace todo el contenido del archivo antes de la tarea de azure-pipelines.yml publicación por el siguiente fragmento de código:

  trigger:
  - main
  
  strategy:
    matrix:
      jdk10_linux:
        imageName: "ubuntu-latest"
        jdkVersion: "1.10"
      jdk11_windows:
        imageName: "windows-latest"
        jdkVersion: "1.11"
    maxParallel: 2
  
  pool:
    vmImage: $(imageName)
  
  steps:
  - task: Maven@3
    inputs:
      mavenPomFile: "pom.xml"
      mavenOptions: "-Xmx3072m"
      javaHomeOption: "JDKVersion"
      jdkVersionOption: $(jdkVersion)
      jdkArchitectureOption: "x64"
      publishJUnitResults: true
      testResultsFiles: "**/TEST-*.xml"
      goals: "package"
  

• Seleccione Guardar y confirme los cambios para ver que la compilación ejecuta dos trabajos en dos plataformas y SDK diferentes.

Personalización de desencadenadores de CI

Los desencadenadores de canalización hacen que se ejecute una canalización. Puede usar para trigger: hacer que una canalización se ejecute siempre que se inserta una actualización en una rama. Las canalizaciones YAML se configuran de forma predeterminada con un desencadenador de CI en la rama predeterminada (que normalmente es main ). Puede configurar desencadenadores para ramas específicas o para la validación de solicitudes de extracción. Para un desencadenador de validación de solicitud de extracción, reemplace el trigger: paso por como se muestra en los dos ejemplos pr: siguientes. De forma predeterminada, la canalización se ejecuta para cada cambio de solicitud de extracción.

• Si desea configurar desencadenadores, agregue cualquiera de los siguientes fragmentos de código al principio del azure-pipelines.yml archivo.

  trigger:
    - main
    - releases/*
  

  pr:
    - main
    - releases/*
  

  Puede especificar el nombre completo de la rama (por ejemplo, ) o un carácter comodín que coincida con main prefijos (por ejemplo, releases/* ).

Configuración de la canalización

Hay algunas opciones de configuración de canalización que no administra en el archivo YAML, como la ruta de acceso del archivo YAML y el estado habilitado de la canalización. Para configurar estas opciones, vaya a la página de detalles de la canalización y elija Más acciones, Configuración. Para obtener más información sobre cómo navegar y examinar las canalizaciones, vea Navegar por canalizaciones.

En el panel Configuración de canalización puede configurar las opciones siguientes.

• Procesamiento de nuevas solicitudes de ejecución: en ocasiones, querrá evitar que se inicien nuevas ejecuciones en la canalización.

  • De forma predeterminada, el procesamiento de nuevas solicitudes de ejecución es Habilitado. Esta configuración permite el procesamiento estándar de todos los tipos de desencadenador, incluidas las ejecuciones manuales.
  • Las canalizaciones en pausa permiten procesar solicitudes de ejecución, pero esas solicitudes se ponen en cola sin iniciarse realmente. Cuando se habilita el nuevo procesamiento de solicitudes, el procesamiento de la ejecución se reanuda a partir de la primera solicitud de la cola.
  • Las canalizaciones deshabilitadas impiden que los usuarios inicien nuevas ejecuciones. Todos los desencadenadores también están deshabilitados mientras se aplica esta configuración.

• Ruta de acceso del archivo YAML: si alguna vez necesita dirigir la canalización para que use otro archivo YAML, puede especificar la ruta de acceso a ese archivo. Esta configuración también puede ser útil si necesita mover o cambiar el nombre del archivo YAML.

• Vincular automáticamente los elementos de trabajo incluidos en esta ejecución: los cambios asociados a una ejecución de canalización determinada pueden tener elementos de trabajo asociados a ellos. Seleccione esta opción para vincular esos elementos de trabajo a la ejecución. Cuando se selecciona Vincular automáticamente los elementos de trabajo incluidos en esta ejecución, debe especificar una rama específica o para todas las ramas, que es el valor predeterminado. Si especifica una rama, los elementos de trabajo solo se asocian a ejecuciones de esa rama. Si especifica * , los elementos de trabajo se asocian para todas las ejecuciones.

  

  • Para obtener notificaciones cuando se producirá un error en las ejecuciones, consulte Administración de notificaciones para un equipo.

Creación de un elemento de trabajo en caso de error

Las canalizaciones de YAML no tienen una configuración Crear elemento de trabajo en caso de error, como las canalizaciones de compilación clásicas. Las canalizaciones de compilación clásicas son una sola fase y Crear elemento de trabajo en caso de error se aplica a toda la canalización. Las canalizaciones YAML pueden ser de varias fases y es posible que una configuración de nivel de canalización no sea adecuada. Para implementar Create work item on failure in a YAML pipeline (Crear elemento de trabajo en caso de error en una canalización de YAML), puede usar métodos como la llamada API REST Elementos de trabajo - Crear o el comando az boards work-item create de la CLI de Azure DevOps en el punto deseado de la canalización.

En el ejemplo siguiente se tienen dos trabajos. El primer trabajo representa el trabajo de la canalización, pero si se produce un error, el segundo trabajo se ejecuta y crea un error en el mismo proyecto que la canalización.

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

En el ejemplo anterior se usan parámetros runtime para configurar si la canalización se realiza correctamente o no. Al ejecutar manualmente la canalización, puede establecer el valor del succeed parámetro . El segundo paso del primer trabajo de la canalización evalúa el parámetro y script solo se ejecuta cuando se establece en succeedsucceed false.

El segundo trabajo de la canalización tiene una dependencia en la primera canalización y solo se ejecuta si se produce un error en el primer trabajo. El segundo trabajo usa el Azure DevOps comando az boards work-item create de la CLI para crear un error. Para más información sobre cómo ejecutar Azure DevOps comandos de la CLI desde una canalización, consulte Ejecución de comandos en una canalización de YAML.

En este ejemplo se usan dos trabajos, pero este mismo enfoque se podría usar en varias fases.

Pasos siguientes

Ha aprendido los conceptos básicos de la personalización de la canalización. A continuación, se recomienda obtener más información sobre cómo personalizar una canalización para el lenguaje que se usa:

• .NET Core
• Contenedores
• Go
• Java
• Node.js
• Python

O bien, para aumentar la canalización de CI a una canalización de CI/CD, incluya un trabajo de implementación con pasos para implementar la aplicación en un entorno.

Para obtener más información sobre los temas de esta guía, vea Trabajos,Tareas , Catálogode tareas , Variables, Desencadenadoreso Solución de problemas.

Para saber qué más puede hacer en las canalizaciones de YAML, consulte Referencia de esquema de YAML.