Pide tu presupuesto ya!

Reparar canalizaciones rotas de Azure DevOps: una guía sistemática

Su Azure DevOps el oleoducto acaba de fallar. De nuevo. Su ventana de implementación se cerró hace una hora, las partes interesadas están esperando una explicación y el mensaje de error tiene tanto sentido como la documentación de expresiones regulares. El cronómetro corre, sus opciones se están reduciendo y en algún lugar de la infraestructura de Azure, un recurso que no sabía que existía está bloqueando un progreso que no puede medir.

Las fallas en las tuberías no se anuncian con informes de diagnóstico útiles. Dejan códigos de salida crípticos, mensajes vagos de tiempo de espera y algún que otro resumen de «algo salió mal» que no dice nada. Necesita un enfoque sistemático para aislar el problema real del ruido que genera Azure DevOps.

La falla no está donde aparece el error

Los registros de Azure DevOps muestran dónde se detuvo la canalización, no por qué se detuvo. Un fallido NuGet La tarea de restauración puede indicar que falta un paquete, pero el problema real podría ser un principal de servicio vencido tres capas profundas en tu Configuración RBAC de la suscripción de Azure.

Comience habilitando registro detallado antes de confiar en cualquier mensaje de error.

Habilitar registro detallado

Ponga en cola su canalización manualmente y marque «Habilitar diagnóstico del sistema» antes de ejecutarlo. Para un registro detallado persistente en todas las ejecuciones, defina una variable de canalización:

variables:
  system.debug: true

Esto no sólo agrega más líneas de registro. Activa el Agent.Diagnostic variable (en agentes autohospedados v2.200.0+), que captura registros adicionales para solucionar problemas de red que los registros estándar ignoran.


Consejo profesional: los registros detallados exponen llamadas API entre el agente y los servicios de Azure DevOps. Si una tarea se bloquea sin generar errores, los registros de diagnóstico mostrarán la última llamada API exitosa antes del silencio.


Verifique los registros del agente directamente

Si la canalización falla antes de producir registros útiles, el problema reside en el nivel del agente. Los agentes autohospedados almacenan registros internos en el _diag carpeta en el directorio raíz del agente.

Dos tipos de registros importan:

Tipo de registro Objetivo
Registros de agentes Registro con Azure DevOps, sondeo de trabajos, estado de conectividad
Registros de trabajadores Detalles de ejecución para cada paso del trabajo.

Los agentes alojados en Microsoft no otorgan acceso a estos registros. Si se encuentra con fallas a nivel de infraestructura repetidamente, activar un agente autohospedado donde usted controla el entorno de diagnóstico.

El bloque «Sin paralelismo alojado»

Las nuevas organizaciones de Azure DevOps chocan de inmediato con este muro: ##[error]No hosted parallelism has been purchased or granted. Su canalización no funcionará. No lentamente, no parcialmente: no arranca.

Microsoft deshabilitó las concesiones automáticas de paralelismo de nivel gratuito para nuevos proyectos para evitar abuso de criptominería. Ahora solicitas la subvención manualmente a través de este formulario. La aprobación demora entre 2 y 3 días hábiles.

Solución inmediata

Mientras espera la aprobación de Microsoft, configure un agente autohospedado. Los agentes autohospedados evitan por completo el requisito de concesión de paralelismo. Puede ejecutarlos en una máquina virtual local, una instancia en la nube o incluso un contenedor.

El proceso de configuración:

# Download the agent
Invoke-WebRequest -Uri https://download.agent.dev.azure.com/agent/3.x/vsts-agent-win-x64-3.x.zip -OutFile agent.zip

# Extract and configure
Expand-Archive -Path agent.zip -DestinationPath agent
cd agent
.\config.cmd

Necesitarás:

Una vez configurado, el agente se registra en Azure DevOps y comienza a sondear trabajos.

Fallos de tiempo de espera que no son negociables

Los agentes alojados en Microsoft en la capa gratuita imponen una Tiempo de espera de 60 minutos por trabajo. No hay período de gracia ni advertencia: el trabajo finaliza a las 60:00. Si ejecuta conjuntos de pruebas, publica artefactos de gran tamaño o implementa en varias regiones, alcanzará este límite.

Configuración timeoutInMinutes Un valor superior a 60 en tu YAML no cambia nada:

jobs:
- job: Deploy
  timeoutInMinutes: 120  # Ignored on free tier

Tus opciones

Si su proceso requiere legítimamente más de 60 minutos, está pagando por el paralelismo o administrando sus propios agentes. No hay una tercera opción.

Fallos de red que no puedes ver

Los agentes autohospedados detrás de los firewalls corporativos fallan de manera que no producen mensajes de error útiles. El agente se conecta correctamente a Azure DevOps, busca trabajos, inicia la compilación y luego falla una tarea. ECONNREFUSED o se agota el tiempo en silencio.

El problema: el acceso a la red a nivel de tarea no hereda automáticamente la configuración del proxy del agente.

Configurar el proxy explícitamente

Durante la configuración del agente, especifique su proxy corporativo:

./config.sh --proxyurl http://proxy.company.com:8080 --proxyusername proxyuser --proxypassword proxypass

Esto crea un .proxy archivo en el directorio del agente y expone la configuración del proxy a través de variables de entorno (VSTS_HTTP_PROXY, VSTS_HTTP_PROXY_USERNAME, VSTS_HTTP_PROXY_PASSWORD). Pero las tareas individuales…npm install, git fetch, dotnet restore—debe programarse para comprobar esas variables. No todas las tareas lo hacen.


Verificación de la realidad: su proxy corporativo puede funcionar para la comunicación Azure DevOps del agente, pero fallar para las fuentes NuGet, los registros npm o Docker Hub. La ruta de red de cada tarea es independiente.


El problema del certificado SSL

Si su red corporativa utiliza inspección SSL (un proxy intermediario que vuelve a firmar el tráfico HTTPS), Nodo.jsLas tareas basadas en Rechazarán el certificado del proxy: Error: self signed certificate in certificate chain.

Node.js no utiliza el almacén de certificados del sistema de Windows. Mantiene su propia validación de certificados y rechaza los certificados que no reconoce, incluida su CA raíz corporativa.

La solución:

  1. Exporte su certificado de CA raíz corporativa en formato Base64 (PEM)

  2. Establecer el NODE_EXTRA_CA_CERTS Variable de entorno en la máquina del agente:

[System.Environment]::SetEnvironmentVariable('NODE_EXTRA_CA_CERTS', 'C:\certs\corporate-root-ca.pem', [System.EnvironmentVariableTarget]::Machine)
  1. Reiniciar el servicio del agente

Las tareas que utilizan Node.js ahora confiarán en su cadena de certificados corporativa.

Fallos de Git Checkout que lo bloquean todo

El Checkout La tarea es el punto de entrada de su canalización. Si falla, no se ejecuta nada más. Salga del código 128, «la referencia no es un árbol» o se cuelga en silencio: la forma en que Git le dice absolutamente nada útil.

Los submódulos no se desprotegen automáticamente

Si su repositorio contiene submódulos de git, Tuberías de Azure no los clonará a menos que habilite explícitamente la configuración:

steps:
- checkout: self
  submodules: true

Si los submódulos están en repositorios privados, es posible que el token generado automáticamente por la canalización no tenga permiso para acceder a ellos. Deberá otorgar acceso a la cuenta de servicio de compilación a los repositorios de submódulos o configurar Autenticación HTTPS con PAT.


Advertencia: la recuperación superficial mejora el rendimiento pero interrumpe las operaciones que dependen del historial de Git. Si su canalización calcula versiones a partir de etiquetas o valida solicitudes de extracción, necesitará el historial completo.


Operaciones de fusión de rupturas de búsqueda superficial

Los nuevos oleoductos creados después de septiembre de 2022 tienen un alcance poco profundo (fetchDepth: 1) habilitado de forma predeterminada para mejorar el rendimiento. Esto descarga solo la confirmación más reciente, no el historial completo de Git.

Si su canalización valida solicitudes de extracción o calcula números de versión a partir de etiquetas Git, la búsqueda superficial interrumpe esas operaciones. Las confirmaciones o etiquetas a las que hacen referencia sus scripts no existen localmente.

Colocar fetchDepth: 0 para clonar el historial completo:

steps:
- checkout: self
  fetchDepth: 0

Costo de rendimiento: los repositorios más grandes con un historial profundo tardan más en clonarse. Estás intercambiando velocidad por integridad.

La restauración de NuGet falla con 401/403

Los errores de restauración de paquetes suelen indicar que faltan paquetes. En Azure DevOps, son más frecuentes los problemas de permisos.

Si estas usando Artefactos azures Como fuente privada, la cuenta de servicio de compilación necesita permiso explícito para acceder a ella. De forma predeterminada, se utiliza la identidad con ámbito de colección. Para las nuevas canalizaciones clásicas, el alcance de la autorización del trabajo se establece en el proyecto actual de forma predeterminada, lo que evita que el agente de compilación acceda a las fuentes de otros proyectos.

Opciones de resolución:

La primera opción es más rápida. El segundo es más seguro si realmente desea un aislamiento a nivel de proyecto.

Falta NuGet.config

Si extrae paquetes de fuentes públicas (nuget.org) y privadas (Azure Artifacts), Azure Pipelines necesita una nuget.config para asignar los ID de los paquetes al feed correcto.

Sin él, verás NU1101: Unable to find package errores para paquetes privados, aunque existan en su feed y el servicio de compilación tenga permiso.

Crear un nuget.config en la raíz de tu repositorio:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="AzureArtifacts" value="https://pkgs.dev.azure.com/{org}/_packaging/{feed}/nuget/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

Compromételo. El NuGetCommand La tarea lo utilizará automáticamente.

Errores de sintaxis de YAML que parecen fallas de infraestructura

YAML es sensible a la sangría. Un espacio adicional, un guión faltante o un formato de lista incorrecto producen errores que van desde «canalización no encontrada» hasta fallas silenciosas en las que los trabajos nunca se ejecutan. YAML: donde los espacios en blanco tienen opiniones.

Antes de realizar cambios en YAML, valide la sintaxis mediante la API REST de Azure DevOps. Vista previa del punto final de ejecuciones. Puedes llamarlo vía az rest o el botón «Validar» del editor web de Azure DevOps:

az rest --method post \
  --uri "https://dev.azure.com/{org}/{project}/_apis/pipelines/{pipelineId}/preview?api-version=7.1-preview.1" \
  --body '{"previewRun": true}' \
  --resource "499b84ac-1321-427f-aa17-267ca6975798"

Esto detecta violaciones de esquema antes de que bloqueen su implementación.

Límites de longitud de ruta en Windows

Windows impone un límite de longitud de ruta de 260 caracteres de forma predeterminada. profundamente anidado node_modules Los directorios, las rutas de artefactos de varios niveles o los nombres de ramas largos superan este límite durante los pasos de pago o publicación.

El oleoducto falla con The specified path, file name, or both are too long o errores de archivo no encontrado que no tienen sentido.

Habilite el soporte de ruta larga:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Requiere un reinicio. Si está en agentes alojados en Microsoft, no controla la configuración del sistema operativo; en su lugar, reestructura las rutas de sus artefactos.

Utilice Sysinternals para el diagnóstico a nivel de proceso

El Extensión Sysinternals Azure DevOps integra ProcDump y ProcMon directamente en tareas de canalización. Esto aborda escenarios en los que las pruebas fallan de forma intermitente, las compilaciones consumen demasiada memoria o los bloqueos de archivos bloquean la publicación de artefactos. Finalmente, un registro que realmente le dice lo que sucedió en lugar de lo que no sucedió.

ProcDump: capturar volcados de caída

- task: Sysinternals.ProcDump@1
  displayName: 'Capture Crash Dump with ProcDump'
  inputs:
    processName: 'dotnet.exe'
    dumpType: 'Full'
    delay: 15
    artifactName: dotnet_dumps

Cuando el proceso de destino activa el umbral configurado (retraso, CPU o memoria), ProcDump genera un volcado de memoria y lo carga como un artefacto de canalización. Lo descargas post-mortem y lo analizas con WinDbg o estudio visual.

Los volcados de memoria le indican por qué falló un proceso. Pero a veces es necesario ver qué hacía mientras aún estaba vivo.

ProcMon: registrar la actividad del sistema de archivos

- task: sysinternals.procmon@1
  displayName: 'Procmon'
  inputs:
    logFile: procmonlog
    artifactName: procmon_logs

ProcMon registra cada archivo, registro y operación de proceso. Si una compilación falla con «archivo en uso» o «acceso denegado», el registro de ProcMon muestra exactamente qué proceso bloqueó el archivo y cuándo.

El problema rara vez es obvio

Cascada de fallas en las tuberías. Una entidad de servicio caducada bloquea la publicación de artefactos, lo que desencadena un tiempo de espera que produce un mensaje de error vago que apunta a una tarea completamente incorrecta. Se soluciona el síntoma (el tiempo de espera) y la siguiente ejecución falla en un paso diferente porque la causa raíz (la entidad de servicio) sigue sin funcionar.

Trabaje hacia atrás desde el fracaso. Habilite el registro detallado. Verifique el diagnóstico del agente. Verifique las rutas de red y las cadenas de certificados. Confirme los permisos en cada límite: alcance del proyecto, acceso a fuentes, suscripción RBAC, listas permitidas de firewall.

Azure DevOps no le da la respuesta. Le entrega fragmentos de registro, mensajes de error parciales y límites de infraestructura disfrazados de problemas de configuración. El diagnóstico sistemático (capa por capa, límite por límite) es el único método que escala.

Written by

Leave a comment