Personalización de la canalización

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

A continuación tiene una guía paso a paso sobre las formas habituales de personalizar una 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 archivo azure-pipelines.yml

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 correspondiente.

Nota:

Para obtener instrucciones sobre cómo ver y administrar las canalizaciones en el portal de Azure DevOps, consulte Visualización y administración de las 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 solo 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 incluyan 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 la acción Editar 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 valor vmImage:

  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 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.

• 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 archivo azure-pipelines.yml, reemplace este contenido:

  pool:
    vmImage: "ubuntu-latest"
  

  por 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 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 usando 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 varias versiones, agregue la siguiente matriz al archivo azure-pipelines.yml antes de la tarea de 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 variable $(imageName) a la plataforma que prefiera.

• Si desea compilar en varias plataformas y versiones, reemplace todo el contenido del archivo azure-pipelines.yml 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 validar solicitudes de incorporación de cambios. Para un desencadenador de validación de solicitudes de incorporación de cambios, reemplace el paso trigger: 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 cualquiera de los fragmentos de código siguientes al principio del archivo azure-pipelines.yml.

  trigger:
    - main
    - releases/*
  

  pr:
    - main
    - releases/*
  

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

Configuración de la canalización

Puede ver y configurar las opciones de canalización en el menú Más acciones de la página de Detalles de la canalización.

• Administración de la seguridad - Administración de la seguridad
• Cambiar el nombre o mover: edite el nombre de la canalización y la ubicación de la carpeta.
• Distintivo de estado - Adición de un distintivo de estado de flujo de trabajo al repositorio
• Eliminar: elimina la canalización, incluidas todas las compilaciones y artefactos asociados.
• Ejecuciones programadas - Vista de ejecuciones programadas

Elija Configuración para configurar las siguientes opciones de canalización.

En el panel Configuración de canalizaciones 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 estado de 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 que se lleguen a iniciar. Cuando se habilita el nuevo procesamiento de solicitudes, la ejecución del procesamiento 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 esté aplicada esta configuración. Todas las directivas de compilación que usan una canalización deshabilitada mostrarán el mensaje "No se puede poner la compilación en cola" junto a la directiva de compilación en la ventana de información general de la solicitud de incorporación de cambios y se romperá el estado de la directiva de compilació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. Seleccione esta opción para vincular esos elementos de trabajo a la ejecución. Si 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 asociarán a ejecuciones de esa rama. Si especifica *, los elementos de trabajo se asociarán a todas las ejecuciones.

  

  • Para recibir notificaciones cuando se produzca un error en las ejecuciones, consulte Administración de notificaciones para un equipo.

Administrar seguridad

Puede configurar la seguridad de canalizaciones en un nivel de proyecto desde Más acciones en la página de aterrizaje de canalizaciones y en un nivel de canalización en la página de detalles de la canalización.

Para dar soporte técnico a las operaciones de la canalización, puede agregar los usuarios a un grupo de seguridad integrado, establecer los permisos individuales de un usuario o grupo, o bien agregar usuarios a roles predefinidos. Puede administrar la seguridad desde Azure Pipelines en el portal web, desde el contexto de usuario o del administrador. Para obtener más información sobre cómo configurar la seguridad de canalizaciones, consulte Permisos de canalización y roles de seguridad.

Crear elemento de trabajo en caso de error

Las canalizaciones YAML no tienen la 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 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 Crear elemento de trabajo en caso de error en una canalización YAML, puede usar métodos como la llamada API de REST Elementos de trabajo: creación 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 le 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, consulte Tipos de elementos de trabajo (WIT).

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

El segundo trabajo de la canalización tiene una dependencia en el 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 obtener 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 YAML.

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

Nota:

También puede usar una extensión de Marketplace, como Crear error en caso de error de versión, que tiene compatibilidad con las 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 usado:

• .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á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.