Documentazione e comunicazione non sono contorno del DevOps: sono il meccanismo con cui il flusso di lavoro resta osservabile. Su AZ-400 la domanda non è “come creo una pagina wiki” ma “dato questo requisito di tracciabilità o notifica, quale strumento e con quale ciclo di vita”. Diamo per acquisiti i meccanismi base e concentriamoci sulle decisioni di design e sui trade-off.

Dove vive la documentazione: project wiki o code wiki

In Azure DevOps ogni team project può avere un wiki, ma il repository Git che lo alimenta non viene creato di default. La prima decisione è quale dei due modelli adottare: hanno cicli di vita opposti.

Il project wiki è unico per progetto, è alimentato da un repo Git dedicato con nome convenzionale NomeProgetto.wiki e si modifica dal portale. È deliberatamente a bassa frizione: chi appartiene al gruppo Contributors pubblica subito, senza pull request. Nota architetturale: quel repo non compare in Repos né in Project Settings, quindi non è governabile con gli stessi criteri degli altri repo. È la scelta giusta per runbook, decisioni di team e onboarding, dove il costo di un errore è basso.

Il publish code as wiki (code wiki) pubblica i file Markdown già presenti in un repo di prodotto, specificando repository, branch e un mapped path. Il contenuto eredita quindi tutta la governance del codice: branch policy, revisione in pull request, versionamento per branch. Serve la permission Create Repository, di default assegnata al gruppo Project Administrators. È la scelta giusta quando la documentazione deve essere coerente con una specifica versione del software — reference di API, note di architettura che cambiano con la release — o quando la compliance impone approvazione su ogni modifica. È anche l’unico modo per avere più wiki nello stesso progetto.

Il trade-off è velocità contro tracciabilità. Se il requisito parla di revisione obbligatoria, versionamento con il codice o documentazione per branch, la risposta è code wiki; se parla di aggiornamento immediato da parte del team, è il project wiki. Dettaglio spesso decisivo: gli utenti con accesso Stakeholder leggono il wiki ma non possono crearlo, perché non hanno permessi su Repos.

Diagrammi come codice: Mermaid e i suoi vincoli

Mermaid descrive diagrammi in testo, quindi permette di versionarli, revisionarli in PR e mantenerli allineati al codice — l’alternativa è l’immagine binaria, che invecchia in silenzio e non è diffabile. Il wiki di Azure DevOps supporta vari tipi, tra cui sequence, flowchart, class, state, gantt, user journey, pie, requirements, gitgraph, entity relationship e timeline, scritti in un blocco recintato con l’identificatore mermaid o nel container :::.

Il vincolo da conoscere è che il supporto sintattico è parziale: risultano non supportati, tra gli altri, la maggior parte dei tag HTML, Font Awesome, la keyword flowchart (va usato graph) e le frecce lunghe. Conseguenza di design: un diagramma che rende in un editor Mermaid generico può non rendere nel wiki. Se il requisito è “diagrammi identici su più piattaforme”, il rendering nativo non basta e va valutata la generazione dell’immagine in pipeline.

Release notes generate dalla history

Scrivere a mano le release notes è un lavoro che degrada: viene saltato sotto pressione, proprio quando serve. La strategia è derivarle dai metadati che il team già produce, e la decisione è quale sorgente sia autorevole.

Su GitHub le release notes generate automaticamente si costruiscono dalle pull request mergiate, dai contributor e dal link al changelog completo. Il file .github/release.yml permette di raggrupparle in categorie basate sulle label delle PR, con la label jolly "*" come catch-all, e di escludere PR per label o per autore, inclusi i bot. Il trade-off implicito è che la qualità dipende dalla disciplina di labeling: se la label è opzionale, tutto finisce nel catch-all. Design corretto: label obbligatoria come check di PR, così la categorizzazione è un invariante e non una buona intenzione.

Da Azure Pipelines, il task GitHubRelease@1 crea, modifica o elimina una release su GitHub tramite una service connection GitHub con permesso Write, e genera un changelog fra la release corrente e una precedente. Le due leve importanti sono changeLogType, che sceglie fra commitBased (elenco dei commit) e issueBased (issue e pull request, categorizzabili per label), e changeLogCompareToRelease, che fissa il termine di paragone fra ultima release completa, ultima non-draft o ultima non-draft individuata per tag. La decisione è a chi si parla: un changelog commit-based è per gli sviluppatori e riflette la granularità del repo; uno issue-based è per stakeholder e clienti e riflette il valore consegnato. Il confronto per tag serve quando esistono canali paralleli, preview e stabile, dove il delta con l’ultima release qualsiasi sarebbe privo di senso.

Webhook, service hook e integrazione con Teams

I service hook di Azure DevOps invertono il controllo rispetto al polling: un publisher definisce eventi, una subscription li ascolta e attiva azioni su un consumer esterno. La scelta è fra consumer preconfezionato — ne esistono molti, tra cui Microsoft Teams, Slack, Jenkins, Datadog, Azure Service Bus e Azure Storage — e il consumer Webhooks, fallback per qualsiasi servizio con endpoint pubblico. Preferisci il consumer dedicato quando esiste: l’azione è già modellata. Passa al webhook quando serve logica custom.

Sul webhook le decisioni rilevanti sono di sicurezza e di superficie dati. L’endpoint deve essere HTTPS, obbligatorio con basic authentication, e non può puntare a localhost o a indirizzi in range speciali; dietro rete privata vanno consentiti in ingresso gli intervalli IP di Azure DevOps. L’impostazione Resource details to send ammette All, Minimal o None: scegliere Minimal riduce il payload e soprattutto il raggio di esposizione dei dati, obbligando il consumer a richiamare Azure DevOps e a superare i normali controlli di permesso per il dettaglio. È il pattern corretto verso servizi di terze parti. Lato governance, per creare subscription servono i permessi Edit subscriptions e View subscriptions, di default riservati ai project administrator, e una subscription creata da chi non ha accesso alla risorsa non si attiva.

Su GitHub il modello è analogo ma l’ambito è esplicito — repository, organizzazione, GitHub App, account Marketplace o Sponsors — e la sicurezza si basa su un secret: la firma HMAC-SHA256 viaggia nell’header X-Hub-Signature-256 e va confrontata con un algoritmo a tempo costante. Un receiver che valida con un confronto di stringhe ordinario è un difetto.

Per Microsoft Teams il vincolo strutturale è di identità: si collegano solo organizzazioni Azure DevOps nello stesso tenant Microsoft Entra dell’account Teams, e indirizzi email uguali su tenant diversi non bastano. Poiché i connettori Office 365 in Teams sono ritirati, l’integrazione passa dalle app dedicate: Azure Boards per creare e monitorare work item, anche convertendo messaggi del canale; Azure Pipelines per sottoscrivere build completate, release e approvazioni pending, approvandole dal canale; Azure Repos per commit e pull request. Queste app esistono su Azure DevOps Services, non su Azure DevOps Server. Lato GitHub, l’app GitHub for Teams permette di sottoscrivere repository e organizzazioni e di agire — aprire e chiudere issue, commentare PR, approvare deployment — dal canale.

La decisione ricorrente è notifica o azione. Se il requisito è “il team deve sapere”, basta una subscription verso un canale. Se è “il gate di approvazione non deve far cambiare strumento”, serve l’app che porta l’azione dentro Teams. Se è “reagire con logica propria”, è un webhook custom.

Trappole tipiche d’esame

  • “La documentazione deve essere revisionata in pull request e versionata col codice”, oppure “servono più wiki nello stesso progetto” → publish code as wiki da branch e mapped path; il project wiki è uno solo e pubblica senza revisione.
  • “Le release notes devono elencare le funzionalità per gli stakeholder, non i commit” → changelog issue based con categorizzazione per label, o release notes generate da GitHub via .github/release.yml.
  • “Il changelog deve confrontare con l’ultima release stabile, ignorando le preview” → changeLogCompareToRelease su ultima release completa o su tag, non sull’ultima non-draft.
  • “Un servizio esterno deve ricevere gli eventi ma non i dati sensibili del work item” → webhook con Resource details to send su Minimal o None: il consumer richiama l’API con le proprie credenziali.
  • “Le approvazioni di deployment vanno gestite senza uscire dal canale del team” → app Azure Pipelines per Teams; un webhook di sola notifica non consente di approvare.
  • “L’integrazione con Teams non si configura” → verifica che organizzazione Azure DevOps e Teams siano nello stesso tenant Microsoft Entra.
  • “Il receiver deve accettare solo payload realmente provenienti da GitHub” → validazione della firma X-Hub-Signature-256 a tempo costante, non un controllo dell’IP mittente.