Using Azure DevOps Wiki helps teams create and share project documentation in one central place. The wiki supports collaboration and requires good organization and visual aids to be effective. You should structure content using logical folders and clear naming conventions, grouping related pages like "Architecture" or "Processes" together.
Markdown is a simple text language used to style wiki pages. It allows you to create headings, tables, and hyperlinks without complex tools. For example, you create a main heading with a single hash symbol (#) and a table using pipes (|) and dashes (-). Using Markdown ensures all documentation has a clean, consistent look.
Mermaid lets you create diagrams directly inside your Markdown pages. You embed a diagram by placing its code inside a special code block marked with triple backticks and the word mermaid. This turns plain text into visual flowcharts or sequence diagrams, making complex ideas easier to understand.
For a wiki to be useful, the right people need to contribute. You configure access permissions to control who can view, edit, or manage pages. Typically, you give read and write access to all team members for collaboration, while granting administrative rights to a few key people responsible for the overall structure and quality.
This area covers setting up automated systems that create and publish release notes and API documentation as part of your Azure DevOps pipeline. Instead of writing documentation manually, you configure tools to generate it automatically from your code and configuration files.
Release documentation tells developers and stakeholders what changed in each deployment. You use the Azure CLI to manage API releases with commands like az apim api release create. The --notes parameter lets you attach description text to a release, which appears in change logs for users to read.
You integrate Azure DevOps pipelines with templating tools and Swagger/OpenAPI generators to produce documentation automatically. These generators read machine-readable API descriptions and create human-readable documentation. Templating tools generate versioned release notes that update themselves with each new release.
Once generated, you configure pipeline tasks to publish documentation to where users can find it. You can push it to code repositories (versioned with source code), wikis (for internal knowledge), or Azure API Management portals (for external developers). Your pipeline can publish to multiple destinations at once.
To extract documentation from your repository, the pipeline first gathers raw data from the repository's history. Developers use the Git Command Line Interface (CLI) or programming libraries to extract commit logs, pulling messages, author details, and timestamps as an early step in the build.
The pipeline then converts this raw commit history into a readable format. Using templated scripts or Azure DevOps pipeline extensions, it transforms the text into structured files. Common output formats include Markdown files for repository platforms, HTML pages for web portals, or PDF documents for official release notes.
After transformation, the pipeline automatically publishes the generated documentation. This release process can run on a schedule or trigger with each new build. Automating this step ensures change logs and API references are updated without manual intervention, giving teams immediate access to the latest documentation.
Azure Pipelines orchestrates the entire lifecycle of parsing, transforming, and publishing documentation. Integrating this workflow into the core continuous integration and continuous delivery (CI/CD) pipeline means every code commit can trigger documentation generation. This automated orchestration guarantees consistency and eliminates human error.
Using HTTP Webhooks is a key strategy for event-driven workflows in Azure. Instead of regularly checking for updates, webhooks wait for specific events and execute actions, which optimizes workflows and reduces unnecessary API calls.
Configuring a webhook involves selecting event triggers (like receiving an email), specifying endpoint URLs, and setting up filter criteria. For example, you might set a trigger to wait for an event from Azure Event Hubs before starting a workflow.
To securely transmit webhook payloads, you use HMAC signatures or shared secrets for validation. Each message includes a signature verifying its authenticity. Configuring security like Transport Layer Security (TLS) and verifying Microsoft Entra ID authentication protects data during transmission.
You also set up retry policies and back-off strategies to handle delivery failures. If the first delivery attempt fails, it retries after a specified delay. Monitoring delivery logs helps detect and resolve issues, ensuring reliable integration.
To connect Azure Boards with a GitHub repository, you create an OAuth-based service connection. You start by installing the Azure Boards app from the GitHub Marketplace, granting it permissions to read and write to your chosen repositories. Then, within your Azure DevOps project settings, you create a new GitHub service connection and authenticate using your GitHub credentials.
Configuring the integration involves setting the right permissions. When installing the Azure Boards GitHub app, you select which repositories it can access. It needs write permissions to create comments and links on commits and pull requests. In Azure DevOps, you need project administration rights to set up the service connection.
After setup, you verify the integration by checking that commits and pull requests in GitHub automatically link to work items in Azure Boards. For example, mentioning a work item number like AB#123 in a GitHub commit message links that commit to work item 123. This creates end-to-end traceability, allowing teams to see the complete history from a work item to the code.
Service hooks and webhooks are automated communication tools that connect Azure DevOps or GitHub to external services like Microsoft Teams. When an important event happens—such as a new build or a pull request—these tools automatically send a notification to a designated Microsoft Teams channel. This keeps everyone informed in real time without manual checks.
To connect Azure DevOps to Microsoft Teams, you create a service hook within your project's settings. You navigate to project settings, select Service hooks, choose Microsoft Teams as the target, and specify which events should trigger a notification. You also configure authentication settings to ensure only authorized systems can send messages to your Teams channel.
GitHub webhooks work similarly. You set up a webhook in your GitHub repository settings, pointing it to your Microsoft Teams channel. When configuring, you can customize the payload—the data sent with each notification—to include useful metadata like build status or a link to details. Authentication scopes control who can set up or modify webhooks, keeping the integration secure.
Connecting development tools to Microsoft Teams enhances collaboration through real-time notifications. Team members see updates directly in their chat channel, keeping everyone aligned. These integrations automate updates, reducing manual work and preventing missed notifications. Using proper authentication ensures only authorized personnel can configure or receive these messages.
Seeking the thrill of transformative tech? Explore the art of designing and implementing DevOps solutions on Azure. Master the shift towards CI/CD, testing, and delivery, while preparing for the Designing and Implementing Microsoft DevOps Solutions exam!
Prepare and test your skills
Prepare and test your skills
You create diagrams by embedding Mermaid code blocks inside your Markdown pages using triple backticks and the word 'mermaid'. This turns plain text into visual flowcharts or sequence diagrams directly within the wiki.
Configuring webhooks enables event-driven workflows that execute actions upon specific triggers, optimizing processes and reducing unnecessary API calls. You secure webhook payloads using HMAC signatures or shared secrets for validation, and you configure Transport Layer Security (TLS) and authentication for secure data transmission.
You automate generation by configuring Azure DevOps pipelines to integrate with templating tools and Swagger/OpenAPI generators that read machine-readable API descriptions. These tools automatically produce human-readable documentation and versioned release notes with each new release.
You establish a connection by installing the Azure Boards app from the GitHub Marketplace and creating an OAuth-based service connection in Azure DevOps. Then, mentioning a work item number like 'AB#123' in a GitHub commit message automatically links that commit to the corresponding work item in Azure Boards.
StudyCerts
StudyCerts