Personalización de la canalización

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

Se trata de 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.

Descripción del 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 Canalizaciones de Azure Pipelines , seleccione la canalización que ha creado y elija Editar en el menú contextual de la canalización para abrir el editor de YAML para la canalización.

Nota

Para obtener instrucciones sobre cómo ver y administrar las canalizaciones en el portal de Azure DevOps, consulte Navegación por canalizaciones.

Examine el contenido del archivo YAML.

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     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 se inició o de las actualizaciones realizadas en Azure Pipelines.

Esta canalización se ejecuta cada vez que el equipo inserta un cambio en la rama principal del repositorio o crea una solicitud de incorporación de cambios. Se ejecuta en una máquina Linux hospedada por Microsoft. El proceso de canalización tiene un único paso, que consiste en ejecutar la tarea de Maven.

Cambio de la plataforma en la que se va a compilar

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 autohospedados 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 una plataforma diferente, como Windows o Mac, cambie el vmImage valor:

    pool:
      vmImage: "windows-latest"
    
    pool:
      vmImage: "macos-latest"
    
  • Seleccione Guardar y confirme los cambios para ver la ejecución de la canalización en otra plataforma.

Adición de pasos

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

  • Abra el editor de YAML para 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.

  • Para ver los resultados de la prueba y la cobertura de código, seleccione la compilación y vaya 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 convenientemente 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 trabajos paralelos suficientes.

Compilación con varias versiones

Para compilar un proyecto con diferentes versiones de ese lenguaje, puede usar una matrix de 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 distintas plataformas.

Nota

No se puede usar strategy varias veces en un contexto.

  • Si desea compilar en una sola plataforma y en varias versiones, agregue la siguiente matriz al azure-pipelines.yml archivo antes de la tarea maven y 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 la $(imageName) variable a la plataforma que prefiera.

  • Si desea compilar en varias plataformas y versiones, reemplace todo el contenido del azure-pipelines.yml archivo antes de la tarea de 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@4
      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 trigger: para hacer que una canalización se ejecute siempre que inserte una actualización en una rama. Las canalizaciones YAML se configuran de forma predeterminada con un desencadenador de CI en la rama predeterminada (que suele ser main). Puede configurar desencadenadores para ramas específicas o para la validación de solicitudes de incorporación de cambios. Para un desencadenador de validación de solicitudes de incorporación de cambios, simplemente reemplace el trigger: paso por pr: , como se muestra en los dos ejemplos siguientes. De forma predeterminada, la canalización se ejecuta para cada cambio de solicitud de incorporación de cambios.

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

    trigger:
      - main
      - releases/*
    
    pr:
      - main
      - releases/*
    

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

Configuración de la canalización

Hay algunas opciones de configuración de canalización que no se administran 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 más información sobre cómo navegar y examinar las canalizaciones, consulte Navegación por canalizaciones.

Configuración de canalización.

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

  • Procesamiento de nuevas solicitudes de ejecución : a veces querrá impedir 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 desencadenadores, incluidas las ejecuciones manuales.
    • Las canalizaciones en pausa permiten procesar las 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 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 usar un archivo YAML diferente, 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 seleccionan los elementos de trabajo Vincular automáticamente 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.

    Vincule automáticamente los elementos de trabajo incluidos en esta ejecución.

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

Las canalizaciones de YAML no tienen un elemento de trabajo Create en la configuración de error , como las canalizaciones de compilación clásicas. Las canalizaciones de compilación clásicas son de 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 ,puede usar métodos como work Items - Create REST API call 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 muestran 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'

Nota

Azure Boards permite configurar el seguimiento de elementos de trabajo mediante varios procesos diferentes, como Agile o Basic. Cada proceso tiene diferentes tipos de elementos de trabajo y no todos los tipos de elemento de trabajo están disponibles en cada proceso. Para obtener una lista de los tipos de elementos de trabajo admitidos por cada proceso, vea Tipos de elementos de trabajo (WIT).

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

El segundo trabajo de la canalización tiene una dependencia del primer trabajo y solo se ejecuta si se produce un error en el primer trabajo. El segundo trabajo usa el comando az boards work-item create de la CLI de Azure DevOps para crear un error. Para más información sobre cómo ejecutar comandos de la CLI de Azure DevOps 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.

Nota

También puede usar una extensión de Marketplace, como Crear error en la versión , que tiene compatibilidad con canalizaciones de varias fases de YAML.

Pasos siguientes

Ha aprendido los conceptos básicos de 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 usa:

O bien, para aumentar la canalización de CI en 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álogo de tareas, variables, desencadenadores o solución de problemas.

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