Collegare Azure Boards: guida passo passo
Crea un elemento di lavoro per ogni test non superato, aggiunge un commento quando il test fallisce di nuovo e lo imposta su uno stato completato quando il test viene superato senza errori. Lo stesso token pubblica anche i risultati dei test e mette in coda le pipeline. Questa guida ti accompagna da zero fino a una connessione verificata ed elenca gli errori che potresti incontrare con le relative cause e soluzioni.
Ultimo aggiornamento:
Mantieni riservate le tue credenziali. Non incollare mai token, chiavi, password o URL di webhook in una chat. Inseriscili solo in Studio → Impostazioni → Integrazioni, dove vengono salvati nel file .env del tuo spazio di lavoro e visualizzati come puntini. Lo stesso vale per un assistente IA: può accompagnarti lungo questa guida, ma non ha mai bisogno del tuo token.
Cosa serve
- Un'organizzazione Azure DevOps Services: https://dev.azure.com/<organization> o https://<organization>.visualstudio.com (Azure DevOps Server installato sulle tue macchine non è supportato).
- Il nome del progetto che riceverà gli elementi di lavoro.
- Un token di accesso personale (PAT) con Elementi di lavoro → Lettura & scrittura e Compilazione → Lettura & esecuzione se usi anche Esegui in CI.
- Conoscere il processo del progetto, perché determina il tipo di elemento di lavoro: Basic include Issue, Epic e Task (non Bug); Agile, Scrum e CMMI includono Bug.
Ottieni le credenziali
- Apri dev.azure.com, poi Impostazioni utente → Token di accesso personali → Nuovo token.
- Seleziona la tua organizzazione, imposta una scadenza e in Ambiti scegli Definiti dall'utente.
- Seleziona Elementi di lavoro → Lettura & scrittura (aggiungi Compilazione → Lettura & esecuzione per Esegui in CI), crea il token e copialo subito. Viene mostrato una sola volta.
- Tienilo negli appunti. Non incollarlo da nessuna parte tranne che nello Studio (passaggio successivo).
Collegalo nello Studio
- Nello Studio, apri Impostazioni → Integrazioni → Collega Azure DevOps.
- Incolla un qualsiasi collegamento da Azure DevOps (una bacheca, un elemento di lavoro o la pagina del progetto) e premi Verifica connessione. Lo Studio memorizza l'organizzazione e il progetto.
- Quando richiesto, inserisci il PAT e premi Salva & verifica. Seleziona il progetto in "Destinazione degli elementi di lavoro".
- Se la verifica indica che il progetto non ha un tipo di elemento di lavoro chiamato Bug, imposta
AZURE_BOARDS_WORK_ITEM_TYPEsu uno dei tipi elencati (in un progetto Basic, Issue) eAZURE_BOARDS_DONE_STATEsu uno stato previsto da quel processo (Basic: Done). - Attiva
AZURE_BOARDS_ENABLED.
Verifica che funzioni
- Verifica connessione mostra "Il token può accedere a N progetti" e "<project> accetta elementi di lavoro di tipo <type>". La verifica esegue solo operazioni di lettura; non crea mai un elemento di lavoro.
- Apri Impostazioni → Integrazioni → Ticket e premi Crea ticket di prova. Viene creato un elemento di lavoro con il tag nexus-test e una schermata allegata.
- Aprilo in Azure Boards, verifica il tag e l'allegato ed eliminalo quando hai finito.
Errori comuni
| Cosa vedi | Causa | Soluzione |
|---|---|---|
| "Azure DevOps ha rifiutato il token" (HTTP 203 o 401) | Il PAT è errato, scaduto, revocato, copiato solo in parte oppure è stato creato in un'altra organizzazione. | Crea un nuovo PAT nella stessa organizzazione di AZURE_DEVOPS_ORG_URL con Elementi di lavoro → Lettura & scrittura e salvalo di nuovo. |
| HTTP 403 | Il PAT è valido ma manca un ambito di autorizzazione, oppure il tuo utente non dispone delle autorizzazioni per quel progetto. | Modifica gli ambiti del PAT (Elementi di lavoro → Lettura & scrittura; Compilazione → Lettura & esecuzione per Esegui in CI), oppure chiedi l'accesso all'amministratore del progetto. |
| HTTP 404 | L'organizzazione o il nome del progetto non esiste, oppure il progetto è stato rinominato. | Incolla un collegamento dal progetto corretto e selezionalo nell'elenco. |
| VS402323 "Il tipo di elemento di lavoro Bug non esiste" | Il processo del progetto non prevede un tipo di elemento di lavoro con quel nome. Un progetto Basic include Issue, Epic e Task, non Bug. | Imposta AZURE_BOARDS_WORK_ITEM_TYPE su un tipo elencato dalla verifica (Basic: Issue) e AZURE_BOARDS_DONE_STATE su uno dei relativi stati (Basic: Done), poi premi di nuovo Verifica connessione. |
| "<project> non ha alcun tipo di elemento di lavoro denominato …" | La stessa causa di VS402323, rilevata da Verifica connessione prima che venga creato qualsiasi elemento. | Imposta AZURE_BOARDS_WORK_ITEM_TYPE su uno dei tipi elencati nel messaggio, oppure scegli un altro progetto. |
| "Questo non è un collegamento ad Azure DevOps" | L'indirizzo non è su dev.azure.com/<organization> o <organization>.visualstudio.com, oppure inizia con http://. | Copia l'indirizzo dalla barra degli indirizzi di Azure DevOps Services. Azure DevOps Server non è supportato. |
| "impossibile raggiungere Azure DevOps (…)" o "non ha risposto entro 20 s" | Questo PC non riesce a raggiungere Azure DevOps: una VPN o un proxy, oppure la rete è assente. | Apri dev.azure.com in un browser sullo stesso PC, poi riprova la verifica. |
| Un test superato non imposta lo stato di completamento | Il processo rifiuta AZURE_BOARDS_DONE_STATE per quel tipo, quindi all'elemento viene aggiunto solo il commento. | Imposta AZURE_BOARDS_DONE_STATE su uno stato di quel tipo (Basic: Done; bug Agile: Resolved). |
| Tutte le verifiche hanno esito positivo, ma non compare alcun elemento di lavoro | AZURE_BOARDS_ENABLED è false; oppure l'esito era FLAKY o relativo all'ambiente; oppure si trattava di un'esecuzione in sandbox; oppure il test ha già un elemento di lavoro aperto (un ulteriore errore aggiunge invece un commento). | Attiva AZURE_BOARDS_ENABLED e usa Crea ticket di prova per verificare la connessione. |
Chiavi di configurazione
| Chiave | Cosa fa | Valore valido | Come verificarlo |
|---|---|---|---|
AZURE_BOARDS_ENABLED | Crea elementi di lavoro Azure per gli errori | true o false | Attiva dopo che Verifica connessione ha avuto esito positivo, poi esegui Crea ticket di prova. |
AZURE_DEVOPS_ORG_URL | Indirizzo dell'organizzazione Azure DevOps | https://dev.azure.com/<organization> o https://<organization>.visualstudio.com | Verifica connessione mostra l'organizzazione; incollando un collegamento, il campo viene compilato. |
AZURE_DEVOPS_PROJECT | Nome del progetto Azure DevOps | Il nome del progetto, esattamente come appare in Azure DevOps | Verifica connessione elenca i progetti visibili al token. |
AZURE_DEVOPS_PAT | Token di accesso Azure DevOps (segreto, salvato solo su questo computer) | Una sola riga, senza virgolette né spazi | Verifica connessione: "token rifiutato" significa che è errato, scaduto o appartiene a un'altra organizzazione. |
AZURE_BOARDS_WORK_ITEM_TYPE | Tipo di ticket Azure per gli errori | Un tipo previsto dal processo del progetto: Bug (Agile, Scrum, CMMI) o Issue (Basic) | Verifica connessione indica "<project> accetta elementi di lavoro di tipo <type>" oppure elenca i tipi disponibili nel progetto. |
AZURE_BOARDS_DONE_STATE | Stato Azure quando il test viene superato | Uno stato di quel tipo di elemento di lavoro: Resolved (bug Agile), Done (issue Basic) | Un esito positivo senza anomalie fa avanzare l'elemento; se il processo rifiuta lo stato, viene aggiunto solo un commento. |
AZURE_PIPELINE_ID | Pipeline Azure da eseguire in CI | L'ID numerico di una pipeline Azure (solo per Esegui in CI) | nexus ci-remote --provider=azure mette in coda quella pipeline; richiede Build → Lettura & esecuzione. |
Per approfondire: tutte le integrazioni, la guida alle impostazioni, risoluzione dei problemi. Altre guide: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
Non riesci ancora a risolvere? Scrivi a [email protected] riportando l'esatta riga di errore mostrata da Studio. Non includere token.