Conectar Azure Boards: guía paso a paso
Crea un elemento de trabajo por cada prueba fallida, añade un comentario cuando la prueba vuelve a fallar y lo marca como completado cuando la prueba se supera sin errores. El mismo token también publica los resultados de las pruebas y pone las canalizaciones en cola. Esta guía te lleva desde cero hasta una conexión verificada y enumera los errores que puedes encontrar con sus causas y soluciones.
Última actualización:
Mantén tus credenciales en privado. Nunca pegues un token, una clave, una contraseña ni una URL de webhook en un chat. Introdúcelos solo en Studio → Configuración → Integraciones, donde se guardan en el archivo .env de tu espacio de trabajo y se muestran como puntos. Lo mismo se aplica a un asistente de IA: puede guiarte por estos pasos, pero nunca necesita tu token.
Qué necesitas
- Una organización de Azure DevOps Services: https://dev.azure.com/<organization> o https://<organization>.visualstudio.com (no se admite Azure DevOps Server en tus propios equipos).
- El nombre del proyecto que recibirá los elementos de trabajo.
- Un token de acceso personal (PAT) con Elementos de trabajo → Lectura & escritura, y Compilación → Lectura & ejecución si también utilizas Ejecutar en CI.
- Conocer el proceso de tu proyecto, ya que determina el tipo de elemento de trabajo: Basic tiene Issue, Epic y Task (no Bug); Agile, Scrum y CMMI tienen Bug.
Obtén las credenciales
- Abre dev.azure.com y ve a Configuración de usuario → Tokens de acceso personal → Nuevo token.
- Elige tu organización, establece una fecha de expiración y, en Ámbitos, selecciona Definido personalizado.
- Marca Elementos de trabajo → Lectura & escritura (añade Compilación → Lectura & ejecución para Ejecutar en CI), crea el token y cópialo ahora. Solo se muestra una vez.
- Mantenlo en el portapapeles. No lo pegues en ningún sitio excepto en Studio (siguiente paso).
Conéctalo en Studio
- En Studio, abre Configuración → Integraciones → Conectar Azure DevOps.
- Pega cualquier enlace de Azure DevOps (un tablero, un elemento de trabajo o la página del proyecto) y pulsa Comprobar conexión. Studio conserva la organización y el proyecto.
- Cuando se te solicite, introduce el PAT y pulsa Guardar & comprobar. Elige el proyecto en "Destino de los elementos de trabajo".
- Si la comprobación indica que el proyecto no tiene ningún tipo de elemento de trabajo llamado Bug, establece
AZURE_BOARDS_WORK_ITEM_TYPEen uno de los tipos que enumera (en un proyecto Basic, Issue), yAZURE_BOARDS_DONE_STATEen un estado que tenga ese proceso (Basic: Done). - Activa
AZURE_BOARDS_ENABLED.
Comprueba que funciona
- Comprobar conexión muestra "El token tiene acceso a N proyectos" y "<project> admite elementos de trabajo de tipo <type>". La comprobación solo lee; nunca crea elementos de trabajo.
- Abre Configuración → Integraciones → Incidencias y pulsa Crear incidencia de prueba. Se crea un elemento de trabajo con la etiqueta nexus-test y una captura de pantalla adjunta.
- Ábrelo en Azure Boards, confirma la etiqueta y el archivo adjunto, y elimínalo cuando termines.
Errores habituales
| Lo que ves | Causa | Solución |
|---|---|---|
| "Azure DevOps rechazó el token" (HTTP 203 o 401) | El PAT es incorrecto, ha expirado, se ha revocado, se ha copiado de forma incompleta o se creó en otra organización. | Crea un nuevo PAT en la misma organización que AZURE_DEVOPS_ORG_URL con Elementos de trabajo → Lectura & escritura, y vuelve a guardarlo. |
| HTTP 403 | El PAT es válido, pero le falta un ámbito, o tu usuario no tiene permisos en ese proyecto. | Edita los ámbitos del PAT (Elementos de trabajo → Lectura & escritura; Compilación → Lectura & ejecución para Ejecutar en CI), o pide acceso al administrador del proyecto. |
| HTTP 404 | La organización o el nombre del proyecto no existe, o se ha cambiado el nombre del proyecto. | Pega un enlace del proyecto correcto y selecciónalo en la lista. |
| VS402323 "El tipo de elemento de trabajo Bug no existe" | El proceso del proyecto no tiene ningún tipo de elemento de trabajo con ese nombre. Un proyecto Basic tiene Issue, Epic y Task, no Bug. | Establece AZURE_BOARDS_WORK_ITEM_TYPE en un tipo que aparezca en la comprobación (Basic: Issue) y AZURE_BOARDS_DONE_STATE en uno de sus estados (Basic: Done), y pulsa Comprobar conexión de nuevo. |
| "<project> no tiene ningún tipo de elemento de trabajo llamado …" | La misma causa que VS402323, detectada por Comprobar conexión antes de registrar nada. | Establece AZURE_BOARDS_WORK_ITEM_TYPE en uno de los tipos indicados en ese mensaje, o elige otro proyecto. |
| "Ese no es un enlace de Azure DevOps" | La dirección no pertenece a dev.azure.com/<organization> ni a <organization>.visualstudio.com, o empieza por http://. | Copia la dirección de la barra del navegador desde Azure DevOps Services. Azure DevOps Server no es compatible. |
| "no se pudo acceder a Azure DevOps (…)" o "no respondió en 20 s" | Este equipo no puede acceder a Azure DevOps: hay una VPN o un proxy, o no hay conexión de red. | Abre dev.azure.com en un navegador en el mismo equipo y vuelve a comprobar la conexión. |
| Superar una prueba no establece el estado de finalización | El proceso rechaza AZURE_BOARDS_DONE_STATE para ese tipo, por lo que solo se añade el comentario al elemento. | Establece AZURE_BOARDS_DONE_STATE en un estado de ese tipo (Basic: Done; error de Agile: Resolved). |
| Todas las comprobaciones son correctas, pero no aparece ningún elemento de trabajo | AZURE_BOARDS_ENABLED es false; o el resultado fue FLAKY o un resultado del entorno; o fue una ejecución en un entorno aislado; o la prueba ya tiene un elemento de trabajo abierto (si el fallo se repite, se añade un comentario en su lugar). | Activa AZURE_BOARDS_ENABLED y usa Crear incidencia de prueba para verificar la conexión. |
Claves de configuración
| Clave | Qué hace | Valor válido | Cómo comprobarlo |
|---|---|---|---|
AZURE_BOARDS_ENABLED | Crear elementos de trabajo de Azure para los fallos | true o false | Activa esta opción cuando Comprobar conexión dé un resultado correcto, y luego ejecuta Crear incidencia de prueba. |
AZURE_DEVOPS_ORG_URL | Dirección de la organización de Azure DevOps | https://dev.azure.com/<organization> o https://<organization>.visualstudio.com | Comprobar conexión muestra la organización; al pegar un enlace, se rellena este campo. |
AZURE_DEVOPS_PROJECT | Nombre del proyecto de Azure DevOps | El nombre del proyecto, exactamente como aparece en Azure DevOps | Comprobar conexión enumera los proyectos a los que tiene acceso el token. |
AZURE_DEVOPS_PAT | Token de acceso de Azure DevOps (secreto, guardado solo en este equipo) | Una sola línea, sin comillas ni espacios | Comprobar conexión: "se rechazó el token" significa que es incorrecto, ha caducado o pertenece a otra organización. |
AZURE_BOARDS_WORK_ITEM_TYPE | Tipo de incidencia de Azure para los fallos | Un tipo disponible en el proceso del proyecto: Bug (Agile, Scrum, CMMI) o Issue (Basic) | Comprobar conexión indica "<project> admite elementos de trabajo de tipo <type>" o enumera los tipos disponibles en el proyecto. |
AZURE_BOARDS_DONE_STATE | Estado de Azure cuando se supera la prueba | Un estado de ese tipo de elemento de trabajo: Resolved (error de Agile), Done (incidencia de Basic) | Si la prueba se supera sin problemas, el elemento cambia de estado; si el proceso rechaza el estado, solo se añade un comentario. |
AZURE_PIPELINE_ID | Canalización de Azure para ejecutar en CI | El identificador numérico de una canalización de Azure (solo para Ejecutar en CI) | nexus ci-remote --provider=azure pone esa canalización en cola; requiere Compilación → Leer y ejecutar. |
Más: todas las integraciones, la guía de Configuración, solución de problemas. Otras guías: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
¿Sigues sin poder avanzar? Escribe a [email protected] e incluye la línea exacta del error que muestra Studio. No incluyas ningún token.