Design and implement processes and communications · Topic 3 of 3
Documentation, Webhooks and Collaboration Integrations
AZ-400 collaboration: wikis, Markdown and Mermaid, release notes, generating docs from Git history, webhooks, service hooks and Microsoft Teams.
- 5 min
- Azure DevOps wikis are Markdown backed by Git. Publish code as wiki keeps docs with the code.
- Mermaid diagrams are text. GitHub uses a fenced
mermaidblock. Azure DevOps wiki uses::: mermaid. - GitHub can auto generate release notes and group them by label.
What it is
Teams that ship often still need shared knowledge: how the system works, what changed in a release and who should hear about an event. This topic covers documentation (wikis, diagrams, release notes, API docs), automation of documentation from Git history, and integrations (webhooks, Azure Boards with GitHub, and Microsoft Teams).
How it works
Wikis, Markdown and Mermaid
| Option | Notes |
|---|---|
| Azure DevOps project wiki | Created for the project. Pages are Markdown, stored in a Git repository behind the scenes, so you can clone, edit and review them like code |
| Publish code as wiki | Publishes Markdown files from a folder in an existing repository as a wiki, so docs live with the code |
| GitHub wiki | A wiki on the repository. Markdown files in the repository itself, rendered on GitHub, are also common |
Markdown is the format for all of these. Mermaid lets you write diagrams as text, so they live in version control and show a readable diff. In GitHub, use a fenced code block with the language mermaid. In an Azure DevOps wiki, wrap the diagram in ::: mermaid and :::. Mermaid supports flowcharts, sequence diagrams, class diagrams, Gantt charts and more.
The diagram text itself is the same in both places:
flowchart LR
Commit --> Build --> Test --> DeployRelease documentation
| Item | How to produce it |
|---|---|
| Release notes | GitHub can generate release notes automatically when you create a release, grouping merged pull requests, and you can configure categories with labels in a .github/release.yml file. In Azure DevOps, use extensions or a script that calls the REST API for the work items and pull requests in a run |
| API documentation | Describe the API with an OpenAPI (Swagger) definition and generate or host the documentation from it, for example in Azure API Management developer portal or a Swagger UI page |
| Changelog | Keep a CHANGELOG.md updated by the pipeline |
Generating documentation from Git history
Commit messages and pull requests are a record of change, so you can build documentation from them.
- Use
git logwith a format, or a range such asgit log v1.2.0..v1.3.0 --pretty=format:"%h %s", to list changes between two tags. - Follow a convention such as Conventional Commits (
feat:,fix:) so a script can group changes by type. - Run the script in the pipeline when a tag is created and publish the output as release notes or a wiki page.
Webhooks and service hooks
A webhook sends an HTTP POST to a URL when an event happens.
| Platform | Details |
|---|---|
| GitHub webhooks | Set a payload URL, a content type and a secret. Choose the events. GitHub signs each delivery with the secret (an HMAC in the X-Hub-Signature-256 header) so the receiver can verify it |
| Azure DevOps service hooks | Create a subscription: a trigger event (build completed, code pushed, work item created) plus an action (a web hook, Slack, Microsoft Teams and other services) |
Always verify the signature or secret on the receiving side and respond quickly. Do long work asynchronously.
Integrating Azure Boards with GitHub
Install the Azure Boards app in GitHub, then connect an Azure DevOps project to one or more repositories. After that, AB# mentions link commits and pull requests to work items, and the work item shows the links. You can also connect from Project settings in Azure DevOps by adding a GitHub connection.
Integrating with Microsoft Teams
- Azure Boards, Azure Repos and Azure Pipelines apps for Teams let a channel subscribe to events, such as a build failing or a pull request being created, and let people act from the channel, for example approving a pipeline deployment.
- GitHub for Microsoft Teams subscribes a channel to repository activity such as issues, pull requests, commits and releases.
- If no app fits, use an incoming webhook or a service hook to post a message to a channel.
Choosing quickly
| Requirement | Answer |
|---|---|
| Docs reviewed in pull requests alongside code | Publish code as wiki, or Markdown in the repository |
| Diagram stored as text in the wiki | Mermaid |
| Release notes from merged pull requests in GitHub | Auto generated release notes |
| Post a message when a build fails | Service hook, or the Azure Pipelines app for Teams |
| Call your own service when code is pushed | A webhook |
A worked scenario
A team keeps architecture notes in a wiki that nobody updates. They move the notes into a docs folder in the repository and publish it as a wiki, so changes go through pull requests. They draw the deployment flow in Mermaid, tag releases with Conventional Commit messages, generate the release notes in the pipeline, and subscribe the team channel in Teams to pipeline failures.
What to remember for the exam
- Azure DevOps wikis are Markdown backed by Git. Publish code as wiki keeps docs with the code.
- Mermaid diagrams are text. GitHub uses a fenced
mermaidblock. Azure DevOps wiki uses::: mermaid. - GitHub can auto generate release notes and group them by label.
- GitHub webhooks use a secret and sign payloads. Azure DevOps uses service hooks.
- Teams apps for Boards, Repos, Pipelines and GitHub subscribe channels to events.
"Documentation that stays up to date" usually means generated from the repository (Git history, OpenAPI file) and published by the pipeline.
How the exam asks about this
- "Keep wiki pages reviewed like code." Publish a repository folder as a wiki.
- "Draw a sequence diagram in the wiki without an image file." Mermaid.
- "Notify an external system when a push happens." A webhook.
- "Approve a deployment from chat." The Azure Pipelines app for Teams.
Common mistakes
Pasting screenshots of diagrams. They cannot be diffed or searched. Use Mermaid.
Ignoring the webhook secret. Anyone could post fake events to your endpoint.
Writing release notes by hand. They drift. Generate them from merged work.
Confusing webhooks with service hooks. A service hook is the Azure DevOps feature that includes webhooks as one action type.
Check yourself
How do you write a diagram as text inside a GitHub Markdown file?
A fenced code block with the language mermaid.
Which GitHub webhook setting lets the receiver verify the sender?
The secret, which signs each payload.
Which Azure DevOps feature sends events to Teams, Slack or a web hook?
Service hooks.
Topic 3 of 3 in Design and implement processes and communications
Test yourself on Design and implement processes and communications
The full Microsoft AZ-400 question bank has 766 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Microsoft. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.