Azure DevOps (AZ-400)
Chapter 2 of 12 · Processes and communications · 75 practice questions

Processes and Communications

What this chapter covers

  • Design and implement a structure for the flow of work, including GitHub Flow
  • Design and implement a strategy for feedback cycles, including notifications and GitHub Issues
  • Design and implement integration for tracking work, including GitHub Projects, Azure Boards, and repositories
  • Design and implement source, bug, and quality traceability
  • Design and implement a dashboard, including flow of work such as cycle times, time to recovery, and lead time
  • Design and implement appropriate metrics and queries for project planning, development, testing, security, delivery, and operations
  • Design and implement documentation using wikis and process diagrams, including Markdown and Mermaid syntax
  • Design and implement release documentation, including release notes and API documentation
  • Design and implement automated documentation generation, including from Git history
  • Design and implement webhooks
  • Configure integration between Azure Boards and GitHub repositories
  • Configure integration between GitHub or Azure DevOps and Microsoft Teams

Domain 1 is worth 10-15% of the exam but it is the glue for everything else: how work is planned, how code changes are tied back to that work, how the team measures flow, and how people find out what happened. Questions are usually short and factual (which widget, which keyword, which process) or small design scenarios (which tool for which audience). Expect to be tested on exact syntax such as AB#123, Fixes AB#123, [[_TOC_]], ::: mermaid and @GitHub subscribe.

The DevOps lifecycle and the services behind each stage
Figure 2.1. The DevOps lifecycle and the services behind each stage

1. Structuring the flow of work

Azure Boards processes

Every Azure DevOps project is created from a process that defines its work item types (WITs), fields, states and backlog levels. Four system processes ship with Azure DevOps Services: Basic, Agile, Scrum and CMMI. System processes are locked; to customize you create an inherited process (Organization settings > Boards > Process > Create inherited process) and then add fields, states, rules, custom WITs and even extra portfolio backlog levels. Hosted XML and On-premises XML are the older process models (Azure DevOps Server uses on-premises XML or inheritance). You cannot simply switch a project from Agile to Scrum base process without changing it to another inherited process derived from that base - for system processes Microsoft documents a supported change path (e.g. Basic to Agile), otherwise you create a new project and move work items.

ProcessRequirement WITPortfolio levelsKey workflow statesPick when
BasicIssueEpicTo Do > Doing > DoneSimplest tracking, small/new teams
AgileUser StoryEpic, FeatureNew > Active > Resolved > ClosedAgile teams, story points
ScrumProduct Backlog ItemEpic, FeatureNew > Approved > Committed > DoneScrum, sprints, Effort field
CMMIRequirementEpic, FeatureProposed > Active > Resolved > ClosedFormal change control, audit, risks
  • Agile tracks size with Story Points; Scrum uses Effort; CMMI uses Size; Basic uses Effort on Issues. Tasks track Remaining Work in all four processes (Basic tracks only Remaining Work on Tasks).
  • CMMI adds Change Request, Issue, Review and Risk WITs - a strong hint in questions that mention auditors, formal reviews or risk registers.
  • Bugs can be tracked as requirements (on the backlog), as tasks (on the taskboard) or not at all - a per-team setting (Team settings > Working with bugs).
  • Removed state hides an item from all backlogs and boards; Closed/Done hides it from product and portfolio backlogs but keeps it on sprint backlogs and boards.
  • State categories (Proposed, In Progress, Resolved, Completed, Removed) are what Analytics, the GitHub integration and the flow widgets reason about - not the custom state names.
Work item hierarchy in the four Azure Boards processes
Figure 2.2. Work item hierarchy in the four Azure Boards processes

Work item hierarchy, iterations and areas

The default hierarchy is Epic > Feature > requirement (User Story / PBI / Requirement / Issue) > Task, linked with Parent/Child links. Each level has its own backlog and board. Area paths model ownership (which team owns which product area) and iteration paths model time (sprints). A team subscribes to one or more area paths and selects the iterations it uses; that selection drives the team's backlogs, boards, sprint pages and the team-scoped widgets on dashboards. Delivery Plans show several teams' backlogs on one calendar timeline with dependency lines, which is the usual answer to 'show cross-team dependencies to management'.

  • Other useful link types: Related, Predecessor/Successor (dependencies), Duplicate/Duplicate Of, Tested By/Tests, Affects/Affected By (CMMI), plus development links: Branch, Commit, Pull Request, Build, Found in build, Integrated in build, GitHub Commit/PR/Issue.
  • Board features that support flow: WIP limits per column, split columns (Doing/Done), Definition of Done per column, swimlanes (e.g. Expedite), card styling rules and tag colors.
  • Stakeholder access (free) can view and edit work items and boards, but cannot use sprint planning tools or the full backlog features; Basic access is needed for most contributor tasks.

GitHub Flow

GitHub Flow is a lightweight, branch-based workflow built for continuous delivery: main is always deployable; every change happens on a short-lived, descriptively named branch; you open a pull request early to start discussion; reviews and CI checks gate the merge; after merge the change is deployed and the branch is deleted. Some teams deploy the branch to a test/staging environment before merging to validate it in production-like conditions. It is close to trunk-based development (Domain 2) but explicitly PR-centred.

GitHub Flow
Figure 2.3. GitHub Flow
  1. Create a branch from main (e.g. feature/1234-login-throttle).
  2. Commit small, well-described changes and push frequently.
  3. Open a pull request (draft PRs signal work in progress); link the issue (Closes #42).
  4. Address review comments; CI checks and required reviewers run via branch protection or rulesets.
  5. (Optional) deploy the branch to a test environment.
  6. Merge (merge commit, squash or rebase), deploy main, delete the branch.
WorkflowLong-lived branchesBest fit
GitHub Flowmain onlyWeb apps/services with continuous deployment
Trunk-basedmain only, very short branchesHigh-frequency CI, feature flags
Git Flowmain, develop, release/, hotfix/Versioned products, scheduled releases
Release Flow (Microsoft)main + release/* cut per sprintLarge services, hotfix cherry-picks

2. Feedback cycles: notifications and GitHub Issues

Fast feedback means the right person learns about a failure, review request or customer report quickly and with context - without drowning in noise. Design feedback loops at several layers: inner loop (IDE, pre-commit hooks, local tests), PR loop (CI checks, code review, CODEOWNERS), release loop (deployment status, approvals) and production loop (alerts, user feedback, incidents).

Azure DevOps notifications

  • Personal subscriptions (User settings > Notifications) - for yourself only.
  • Team and project/default subscriptions (Project settings > Notifications) - e.g. 'build fails' to the requester, 'work item assigned' to the assignee. Admins can opt users out of defaults.
  • Delivery: email, SOAP, or via service hooks to external systems.
  • @mentions in work item discussions, PR comments and wiki pages notify a person or group immediately; #123 links a work item and !45 links a pull request.
  • Following a work item or PR subscribes you to all its changes.

GitHub notifications

  • Watching a repository: All activity, Participating and @mentions, Ignore, or Custom (issues, PRs, releases, discussions, security alerts).
  • Participating notifications fire when you are @mentioned, assigned, a review is requested, or you commented. Team mentions (@org/team) notify all team members.
  • CODEOWNERS automatically requests reviews from owners of changed paths.
  • Delivery via web inbox, email and GitHub Mobile; custom routing of email per organization.
  • Dependabot and code scanning alerts have their own notification settings.

GitHub Issues as a feedback channel

GitHub Issues track bugs, enhancements and tasks next to the code. Issue templates and issue forms (YAML in .github/ISSUE_TEMPLATE/) collect structured reports; config.yml in the same folder can disable blank issues and point users to external support links. Labels, milestones, assignees, issue types (organization-level, e.g. Bug/Feature/Task) and sub-issues (parent/child hierarchy) structure the backlog. GitHub Discussions separate open-ended Q&A from actionable issues.

yaml
# .github/ISSUE_TEMPLATE/bug.yml
name: Bug report
description: Report a defect in the web shop
labels: ["bug", "triage"]
body:
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "e.g. 2.4.1"
    validations:
      required: true
  - type: dropdown
    id: env
    attributes:
      label: Environment
      options: ["Production", "Staging", "Local"]
  - type: textarea
    id: repro
    attributes:
      label: Steps to reproduce
    validations:
      required: true

Closing keywords link a PR or commit to an issue and close it when the change lands on the default branch: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, followed by #42 or owner/repo#42. They work in the PR description and in commit messages, not in PR comments. You can also link manually via the Development sidebar.

3. Integrating work tracking: GitHub Projects, Azure Boards and repos

GitHub Projects

GitHub Projects (the current 'Projects', formerly 'Projects (beta)'; the classic projects are retired) is a spreadsheet-like planning surface over issues and PRs from one or many repositories in an organization or user account. Key capabilities:

  • Views: Table, Board (kanban grouped by a single-select field such as Status) and Roadmap (timeline by date or iteration fields). Each view has its own filter, sort, group and slice.
  • Custom fields: text, number, date, single select and iteration (sprint-like time boxes with breaks). Built-in fields include assignees, labels, milestone, repository, linked PRs, sub-issue progress and parent issue.
  • Built-in workflows: auto-add items from a repo matching a filter, set Status to Done when an item is closed or a PR merged, auto-archive items, auto-close issue when Status becomes Done.
  • Insights: current charts (e.g. items by status/assignee) and historical burn-up charts.
  • Automation beyond built-ins via GitHub Actions and the GraphQL API (gh project CLI commands).
  • Draft issues let planners capture ideas in the project before they belong to a repository.

When to use Boards vs GitHub Projects

NeedAzure BoardsGitHub Projects/Issues
Formal process (CMMI, audit fields, rules)Strong - inherited processesLimited
Multi-level portfolio (Epic/Feature)Native backlogsSub-issues + issue types
Capacity planning, sprint burndownBuilt-inIteration field, basic charts
Cross-team timeline with dependenciesDelivery PlansRoadmap view
Developer-centric, open-source stylePossible via integrationNative
Rich analytics (OData, Power BI)Analytics serviceGraphQL API / Insights

Azure Boards <-> GitHub integration

Install the Azure Boards app from GitHub Marketplace (or start from Project settings > Boards > GitHub connections) and authorize the GitHub repositories to connect to an Azure DevOps project. Authentication can be the GitHub App (recommended), OAuth or a PAT; GitHub Enterprise Server is supported too. Microsoft recommends connecting a repository to projects in only one Azure DevOps organization (otherwise AB# linking can behave unexpectedly), while a project can connect to many repositories. After connecting:

  • AB#123 in a commit message, PR description or GitHub issue description creates a link from work item 123 to that commit/PR/issue. AB# in a PR title or comment does not create a link.
  • Fixes AB#123 (also fix, fixed) moves the work item to the first state in the Resolved category, or the Completed category if there is no Resolved state, when the PR merges to the default branch. You can name a state explicitly, e.g. Closed AB#123.
  • Fixes AB#123, AB#124 transitions only the first item; repeat the keyword (Fixes AB#123, Fixes AB#124) to transition each.
  • From a work item you can create a GitHub branch (work item ... menu > New GitHub branch); PRs from that branch and the merge commit are linked automatically.
  • The work item's Development section shows linked GitHub branches, commits, PRs and their status; the board card shows a GitHub icon and PR status.
  • Add an Azure Boards status badge to the GitHub README to show board column counts.
  • Azure Pipelines can build GitHub repos and link the work items it finds into the run.
text
git commit -m "Throttle login attempts per IP

Implements sliding-window limiter in AuthService.
Fixes AB#4812, Fixes AB#4815
Related to AB#4790"

Azure Repos and Azure Pipelines linking

  • In Azure Repos, mention #123 in a commit message or PR to link it; the PR Work items panel lets you link manually; a branch policy can require linked work items before completion.
  • PR completion options can complete associated work items after merging (state transition to the Resolved/Completed category).
  • Branch and PR creation from the work item form keeps links automatic.
  • Pipelines show Related work items on each run (work items linked to commits since the last successful run) and can add Integrated in build links. YAML deployments to environments show the work items and commits deployed.
  • The work item form's Deployment control shows which release stages/environments the item has reached when pipelines report deployment status.

4. Source, bug and quality traceability

Traceability answers auditors' and engineers' questions: which requirement caused this change, which build contains it, which tests prove it, where is it deployed, and which bug was found in which build. In Azure DevOps the chain is assembled from links, not from a single tool.

End-to-end traceability from requirement to release
Figure 2.4. End-to-end traceability from requirement to release
HopMechanismWhere you see it
Requirement -> branch/commitCreate branch from work item, #123 / AB#123Work item Development section
Commit -> PRPR contains commits; policy 'linked work items'PR overview, work items panel
PR -> buildBuild validation policy; CI triggerPR checks, run summary
Build -> work itemsRelated work items, Integrated in buildRun summary, work item links
Build -> release/envMulti-stage YAML + environmentsEnvironment deployment history
Requirement -> testTest case 'Tests' link, requirement-based suitesTest Plans, Requirements quality
Test result -> bugCreate bug from failed test/runBug 'Found in build', repro steps
  • Requirement-based test suites in Azure Test Plans link test cases to user stories automatically, which feeds the Requirements quality widget and the traceability reports.
  • Automated tests can be associated with test cases and run from a pipeline (Visual Studio Test task, test plan settings) so that results roll up against requirements.
  • Bugs created from a failed test or from the Test & Feedback extension capture build, environment, system info and repro steps automatically.
  • In GitHub the equivalent chain is issue -> branch (Create a branch from the issue) -> PR (Closes #42) -> checks/workflow run -> deployment (environments) -> release (tag + notes).
  • Commit signing, required reviews and immutable audit logs strengthen traceability for compliance.

5. Flow metrics and dashboards

Lead time, cycle time, throughput and WIP

Lead time vs cycle time
Figure 2.5. Lead time vs cycle time
MetricAzure Boards definitionWhat it tells you
Lead timeCreated date -> Completed (Done/Closed)Customer view: request to delivery
Cycle timeFirst In Progress -> CompletedTeam view: how long active work takes
ThroughputItems completed per periodDelivery rate
WIPItems In Progress nowLoad; high WIP lengthens cycle time
VelocityEffort/points completed per sprintPlanning forecast for Scrum teams

Little's Law ties them together: average cycle time = average WIP / average throughput. The Lead Time and Cycle Time widgets are control (scatter) charts with a rolling average and standard deviation band; you configure team, backlog level, swimlanes and time period (up to 365 days). Outliers above the band point at blocked or oversized items.

Cumulative flow diagram (CFD)

Reading a cumulative flow diagram
Figure 2.6. Reading a cumulative flow diagram
  • Each colored band is a board column/state; the top edge is total work, the bottom band is Done.
  • Vertical thickness of the in-progress bands = WIP at that date.
  • Horizontal distance between the arrival line and the departure line = approximate cycle time / lead time.
  • A band that keeps widening signals a bottleneck in that column; flat lines mean nothing is moving; a steep top line means scope is being added faster than it is completed.
  • Available as the in-context CFD on the board and as the Cumulative Flow Diagram dashboard widget.

Velocity, burndown and burnup

  • Velocity (in-context report and widget): planned vs completed vs completed-late per sprint; used with the Forecast tool on the backlog.
  • Sprint burndown (in-context, Analytics-based): remaining work (hours/count/points) against the ideal trend, scope change line and non-working days.
  • Burndown / Burnup widgets (Analytics): track any backlog level across several sprints or a release date, by count or sum of a field; burnup highlights scope growth.
  • Sprint Capacity and Sprint Overview widgets show current sprint health.

DORA metrics

The four DORA metrics
Figure 2.7. The four DORA metrics
DORA metricMeasuresTypical Azure DevOps / GitHub source
Deployment frequencyHow often prod deploys succeedEnvironment history, deployments API
Lead time for changesCommit -> running in productionCommit time vs prod deployment time
Change failure rate% deployments causing incident/rollbackFailed deploys, incident links
Failed deployment recovery timeTime to restore after a bad change (MTTR)Incident open/close, Azure Monitor alerts

In the original four keys the first two measure throughput, the last two stability. DORA renamed 'time to restore service' to failed deployment recovery time in 2023, and in 2024 grouped it with throughput and added deployment rework rate as an instability metric; the exam outline still says time to recovery / MTTR. Note that DORA 'lead time for changes' starts at commit, while Azure Boards 'lead time' starts at work item creation - read the question carefully.

Dashboards and widgets

Dashboards are either team dashboards (owned by a team; team admins edit) or project dashboards (permissions set per dashboard). Widgets can be team-scoped or query-based. Auto-refresh is available, and dashboards are visible to Stakeholders.

A delivery-health dashboard (illustrative mockup)
Figure 2.8. A delivery-health dashboard (illustrative mockup)
WidgetShows
Lead Time / Cycle TimeControl chart of completed items
Cumulative Flow DiagramItem counts per column over time
VelocityPoints/effort or count per sprint
Burndown / BurnupProgress to a target across sprints or a date
Sprint Burndown, Sprint Overview, Sprint CapacityCurrent sprint health
Query Tile / Query Results / Chart for Work ItemsResults of a shared work item query
Build History / Pipeline statusRecent run outcomes and durations
Deployment statusRelease/environment status across stages
Test Results Trend (Advanced)Pass rate and duration across runs, Analytics-based
Requirements qualityTest pass state per requirement
MarkdownStatic text, links, team charter, images

6. Metrics and queries for every area

AreaUseful metricsWhere to get them
Project planningVelocity, burndown/burnup, forecast, scope changeBoards reports, Delivery Plans
DevelopmentPR completion time, review turnaround, PR size, code churnAnalytics, GitHub Insights, Pulse
TestingPass rate, flaky tests, coverage, defect density, escaped bugsTest analytics, Test Results Trend
SecurityOpen vulns by severity, mean time to remediate, secret alertsGHAS/Defender for Cloud DevOps security
DeliveryDeployment frequency, lead time for changes, pipeline pass rate/durationPipelines analytics, environments
OperationsMTTR, change failure rate, availability/SLO, incident countAzure Monitor, Application Insights, incidents

Pipelines analytics (pipeline > Analytics tab) gives pipeline pass rate, test pass rate and pipeline duration reports with failure trends and the top failing tasks. Test analytics add flaky test detection. Security posture for GitHub, Azure DevOps and GitLab repos is aggregated by Microsoft Defender for Cloud DevOps security, including findings from GitHub Secret Protection and GitHub Code Security for Azure DevOps (the new names for GitHub Advanced Security for Azure DevOps).

Work item queries (WIQL)

Queries are written in the query editor or in Work Item Query Language (WIQL). Three query types exist: Flat list of work items, Work items and direct links, and Tree of work items (hierarchy via Parent/Child). Only flat-list queries can drive query charts and query widgets. Shared queries live in Shared Queries folders with their own permissions; My Queries are private. Useful macros: @Me, @Today, @CurrentIteration, @Project, @StartOfMonth, @Follows, @RecentMentions, @TeamAreas.

text
SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo]
FROM WorkItems
WHERE [System.TeamProject] = @Project
  AND [System.WorkItemType] = 'Bug'
  AND [Microsoft.VSTS.Common.Severity] IN ('1 - Critical', '2 - High')
  AND [System.State] NOT IN ('Closed', 'Removed')
  AND [System.CreatedDate] >= @Today - 30
ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.CreatedDate] DESC
text
-- Tree query: Features with all child stories (recursive)
SELECT [System.Id], [System.Title], [System.State]
FROM WorkItemLinks
WHERE ([Source].[System.WorkItemType] = 'Feature'
       AND [Source].[System.IterationPath] UNDER 'Shop\2026')
  AND ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward')
  AND ([Target].[System.WorkItemType] = 'User Story')
MODE (Recursive)
bash
# Run a query from the CLI (azure-devops extension)
az boards query --org https://dev.azure.com/fabrikam --project Shop \
  --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active' \
          AND [System.AssignedTo] = @Me" -o table

Analytics, OData and Power BI

The Analytics service is the reporting store behind most modern widgets and in-context reports. It is enabled by default in Azure DevOps Services and needs the View analytics permission. Three ways to report on it in Power BI:

OptionUse whenNotes
Analytics viewsBusiness users, Boards data, simple filtersDefined in Boards > Analytics views; Power BI Data Connector
OData queries (Power BI OData feed)Custom shapes, aggregation, pipelines/testsMost flexible; server-side $apply aggregation
Power BI Azure DevOps connectorQuick startUses Analytics views under the hood
text
https://analytics.dev.azure.com/fabrikam/Shop/_odata/v4.0-preview/WorkItems?
  $filter=WorkItemType eq 'User Story'
     and StateCategory eq 'Completed'
     and CompletedDate ge 2026-07-01Z
  &$select=WorkItemId,Title,LeadTimeDays,CycleTimeDays,CompletedDate
  &$orderby=CompletedDate desc
text
https://analytics.dev.azure.com/fabrikam/Shop/_odata/v4.0-preview/PipelineRuns?
  $apply=filter(Pipeline/PipelineName eq 'shop-ci'
                and CompletedDate ge 2026-09-01Z)
        /aggregate($count as Total,
                   SucceededCount with sum as Succeeded,
                   FailedCount with sum as Failed)

7. Wikis, Markdown and Mermaid

Project wiki vs code wiki

AspectProject wiki (provisioned)Code wiki (published as code)
CountOne per projectMany; any folder of any Git repo
Backing storeHidden Git repo ProjectName.wikiYour existing repo + branch
EditingWiki UI (or clone the wiki repo)Wiki UI commits to branch, or normal PRs
VersionsSingle versionPublish multiple branches as versions
Review/policiesNo PR flow by defaultBranch policies, PR review apply
Best forTeam handbook, onboarding, meeting notesProduct/API docs that version with code
  • Page order is stored in a .order file per folder; attachments go to .attachments.
  • Page file names encode spaces as hyphens (Release-Process.md); a page can have subpages (stored in a same-named folder).
  • Unpublishing a code wiki removes it from the Wiki hub but keeps the repo content.
  • Wiki search spans all wikis in the project; readers need Read on the backing repo.
  • GitHub has a per-repo wiki (separate repo.wiki.git) and GitHub Pages for published docs; Markdown files in the repo itself (README, docs/) render natively.

Azure DevOps wiki Markdown extras

SyntaxEffect
[[_TOC_]]Table of contents (case-sensitive, first instance only)
[[_TOSP_]]Table of subpages ('Child Pages')
#123Link and preview work item 123 (escape a literal hash with a backslash)
@aliasMention a user or group (notifies them)
::: query-table <query-guid> :::Embed a work item query result
::: video <iframe ...> :::Embed a video
::: mermaid ... ::: or ```mermaidRender a Mermaid diagram
$$ ... $$Math (KaTeX) formulas
markdown
[[_TOC_]]

# Release process

> Owner: @platform-team  - Related epic: #4700

| Stage | Gate | Approver |
|-------|------|----------|
| Test  | Automated tests | none |
| Prod  | Change ticket + approval | Release managers |

- [x] Release branch created
- [ ] Release notes published

```bash
az pipelines run --name shop-cd --branch release/2026.10
```

[[_TOSP_]]

Mermaid turns text into diagrams that live in version control and diff cleanly. Both Azure DevOps wikis and GitHub (Markdown files, issues, PRs, discussions, wikis) render it. Azure DevOps supports sequence, Gantt, flowchart (as graph), class, state, user journey, pie, requirement, gitgraph, ER and timeline diagrams.

mermaid
::: mermaid
graph LR
    A[Work item] --> B[Branch]
    B --> C[Pull request]
    C -->|policies pass| D[CI build]
    D --> E{Tests OK?}
    E -->|yes| F[Deploy to staging]
    E -->|no| B
    F --> G[Prod approval]
    G --> H[Production]
:::
mermaid
```mermaid
sequenceDiagram
    participant Dev
    participant GitHub
    participant Boards as Azure Boards
    participant Pipe as Azure Pipelines
    Dev->>GitHub: push + PR "Fixes AB#4812"
    GitHub->>Pipe: PR trigger (build validation)
    Pipe-->>GitHub: check status
    GitHub->>Boards: link PR to 4812
    Dev->>GitHub: merge to main
    GitHub->>Boards: 4812 -> Resolved
```
mermaid
```mermaid
gantt
    title Release 2026.10
    dateFormat YYYY-MM-DD
    section Build
    Feature freeze      :milestone, m1, 2026-10-09, 0d
    Stabilization       :a1, 2026-10-09, 5d
    section Release
    Ring 0 (internal)   :a2, after a1, 2d
    Ring 1 (canary)     :a3, after a2, 3d
    GA                  :milestone, after a3, 0d
```

8. Release documentation and automated docs

Release notes

Good release notes are generated, not hand-written: they come from structured commit messages, PR titles/labels and linked work items, then are edited for the audience. Options:

  • GitHub automatically generated release notes: on a release (UI or gh release create v2.4.0 --generate-notes) GitHub lists merged PRs and contributors since the previous tag; categories and exclusions are configured in .github/release.yml by label and author.
  • Conventional Commits (feat:, fix:, feat!: / BREAKING CHANGE:) plus tools such as semantic-release, release-please, conventional-changelog or git-cliff produce CHANGELOG.md and compute the next SemVer version (fix = patch, feat = minor, breaking = major).
  • Azure Pipelines: a script or Marketplace task (e.g. a release-notes generator extension) reads the commits and work items associated with the run via the REST API and writes Markdown to the wiki, an artifact or a GitHub release (GitHubRelease@1 task supports changelog generation).
  • Plain git log between two tags is the simplest building block.
yaml
# .github/release.yml - categories for generated release notes
changelog:
  exclude:
    labels: [ignore-for-release, dependencies]
    authors: [dependabot]
  categories:
    - title: Breaking changes
      labels: [breaking-change]
    - title: New features
      labels: [enhancement, feature]
    - title: Bug fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]
bash
# Release notes from Git history between the last two tags
PREV=$(git describe --tags --abbrev=0 HEAD^)
CURR=$(git describe --tags --abbrev=0)
{
  echo "## $CURR ($(date +%Y-%m-%d))"
  echo "### Features"
  git log "$PREV..$CURR" --no-merges --pretty='- %s (%h)' | grep -E '^- feat' || true
  echo "### Fixes"
  git log "$PREV..$CURR" --no-merges --pretty='- %s (%h)' | grep -E '^- fix' || true
  echo "### Work items"
  git log "$PREV..$CURR" --pretty=%B | grep -oE 'AB#[0-9]+' | sort -u | sed 's/^/- /'
} > RELEASE_NOTES.md
yaml
# Azure Pipelines: generate notes and publish to the project wiki
- stage: Docs
  dependsOn: Build
  jobs:
  - job: ReleaseNotes
    steps:
    - checkout: self
      fetchDepth: 0            # full history so git log can walk back to the tags
      fetchTags: true          # new pipelines do not sync tags by default
      persistCredentials: true
    - bash: ./build/release-notes.sh
      displayName: Generate RELEASE_NOTES.md
    - bash: |
        git clone https://$(System.AccessToken)@dev.azure.com/fabrikam/Shop/_git/Shop.wiki wiki
        cp RELEASE_NOTES.md "wiki/Release-Notes/$(Build.BuildNumber).md"
        cd wiki && git add . && git commit -m "Release notes $(Build.BuildNumber)" && git push
      displayName: Publish to wiki

API documentation

  • OpenAPI (Swagger) is the standard contract for REST APIs. In ASP.NET Core, generate it with Swashbuckle/NSwag or the built-in Microsoft.AspNetCore.OpenApi (default in .NET 9+); publish the JSON as a pipeline artifact, render with Swagger UI/Redoc, and import into Azure API Management.
  • DocFX builds a static documentation site from XML doc comments (///) plus Markdown conceptual pages (and can include REST specs); output can be hosted on Azure Static Web Apps, GitHub Pages or committed to a code wiki folder.
  • Other ecosystems: Javadoc, Sphinx/autodoc (Python), TypeDoc, Doxygen.
  • Treat docs as code: generate in CI on every merge to main, fail the build on broken links or missing docs, and version docs alongside the code (code wiki versions or tagged sites).
yaml
# GitHub Actions: build DocFX site and publish to GitHub Pages
name: docs
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '9.0.x' }
      - run: dotnet tool update -g docfx && docfx docs/docfx.json
      - uses: actions/upload-pages-artifact@v3
        with: { path: docs/_site }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/deploy-pages@v4

9. Webhooks and service hooks

Service hooks, webhooks and chat integrations
Figure 2.9. Service hooks, webhooks and chat integrations

Azure DevOps service hooks (Project settings > Service hooks) subscribe a consumer to a publisher event. Publishers include work item created/updated/commented, code pushed, PR created/updated/merge attempted, build completed, run state changed, release deployment completed and more. Consumers include generic Web Hooks (HTTP POST JSON), Azure Service Bus, Azure Storage Queue, Jenkins, Slack, Trello, Grafana, Datadog and others. Filters narrow events (area path, branch, pipeline, state). Creating subscriptions needs the Edit subscriptions permission (Project Administrators by default). Failed deliveries are retried and repeatedly failing subscriptions are disabled - check the History view.

bash
# Create a service hook via REST: POST work-item updates to a webhook
curl -u :$AZDO_PAT -H "Content-Type: application/json" \
  -X POST "https://dev.azure.com/fabrikam/_apis/hooks/subscriptions?api-version=7.1" \
  -d '{
    "publisherId": "tfs",
    "eventType": "workitem.updated",
    "resourceVersion": "1.0",
    "consumerId": "webHooks",
    "consumerActionId": "httpRequest",
    "publisherInputs": { "projectId": "<project-guid>", "workItemType": "Bug" },
    "consumerInputs": { "url": "https://hooks.fabrikam.com/azdo/bugs" }
  }'

GitHub webhooks exist at repository, organization, GitHub App and enterprise level. You choose events (push, pull_request, issues, workflow_run, deployment, release ...), a content type and a secret. GitHub signs each payload with HMAC-SHA256 in the X-Hub-Signature-256 header and identifies it with X-GitHub-Event and X-GitHub-Delivery. A ping event is sent on creation; Recent Deliveries lets you inspect and redeliver payloads. Respond with 2xx within 10 seconds and process asynchronously.

text
import hmac, hashlib

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header looks like 'sha256=<hex>'
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)   # constant-time compare
NeedChoose
Push events to an external system in near real timeService hook / webhook
Reliable, buffered processing by your own workersService Bus or Storage Queue consumer
React inside GitHub with codeGitHub Actions on: issues / pull_request / repository_dispatch
Pull data on a schedule for reportingREST/OData/GraphQL API, not a webhook
Trigger an Azure Pipeline from an external eventIncoming Webhook service connection + resource
yaml
# Azure Pipelines triggered by an external webhook (Incoming WebHook service connection)
resources:
  webhooks:
    - webhook: monitoringAlert         # alias
      connection: AlertWebhookConn     # Incoming WebHook service connection
      filters:
        - path: severity
          value: Sev1
steps:
  - script: echo "Alert ${{ parameters.monitoringAlert.alertName }}"

10. ChatOps with Microsoft Teams

Azure DevOps Services offers three Teams apps - Azure Boards, Azure Pipelines and Azure Repos - each addressed with @azure <service> in a channel. They are Services-only (not Azure DevOps Server) and do not deliver notifications into personal chats. Microsoft 365 (Office 365) connectors and their incoming webhooks are being retired; for custom posts use the Teams Workflows app (Power Automate) 'When a Teams webhook request is received' trigger.

AppKey commands / features
Azure Boards@azure boards signin | link <url> | subscriptions | addAreapath <path>
Azure Boards (UI)Create work item from a message; work item URL previews
Azure Pipelines@azure pipelines signin | subscribe <pipeline url> | subscriptions
Azure Pipelines (UI)unsubscribe all <project url>; approve deployments in channel
Azure Repos@azure repos signin | subscribe <repo url> | subscriptions; PR and push events
GitHub@GitHub signin | subscribe owner/repo [features] | unsubscribe | subscribe list features
text
@azure boards link https://dev.azure.com/fabrikam/Shop
@azure boards addAreapath Shop\Checkout
@azure pipelines subscribe https://dev.azure.com/fabrikam/Shop/_build?definitionId=42
@azure repos subscribe https://dev.azure.com/fabrikam/Shop/_git/shop-web

@GitHub subscribe fabrikam/shop-web reviews workflows
@GitHub subscribe fabrikam/shop-web commits:main
@GitHub subscribe fabrikam/shop-web +label:"priority:high"
@GitHub subscribe fabrikam/shop-web workflows:{event:"push" branch:"main"}
@GitHub unsubscribe fabrikam/shop-web commits
@GitHub subscribe list features
  • GitHub app defaults: issues, pulls, commits, comments, deployments, releases are on. reviews, workflows, branches, discussions and label filters are opt-in.
  • The GitHub app supports actions from Teams: close/reopen issues, comment, and approve deployments waiting on environment protection rules.
  • A Teams channel links to one Azure Boards project at a time; area paths filter which work item events appear.
  • Creating Boards subscriptions in Teams requires Project or Team Administrator rights.
  • Slack has equivalent apps (/azboards, /azpipelines, /github subscribe).

11. Quick review

  • Processes: Basic (Issue), Agile (User Story), Scrum (PBI), CMMI (Requirement + Change Request/Risk/Review). Customize via inherited process.
  • GitHub Flow: main always deployable, short branches, PRs, deploy after merge, delete branch.
  • AB#id links GitHub -> Boards from commit message, PR description or issue description; Fixes AB#id transitions on merge to the default branch.
  • Lead time (created -> done) vs cycle time (in progress -> done); CFD band width = WIP, horizontal distance = cycle time.
  • DORA: deployment frequency, lead time for changes, change failure rate, recovery time.
  • WIQL for live queries (flat / direct links / tree); Analytics views or OData for Power BI.
  • Project wiki = one per project; code wiki = many, versioned with branches, PR-reviewed.
  • [[_TOC_]], [[_TOSP_]], ::: mermaid (use graph, not flowchart, in Azure DevOps).
  • Release notes from Conventional Commits / git log / .github/release.yml; API docs via OpenAPI and DocFX.
  • Service hooks (Azure DevOps) and webhooks (GitHub, HMAC X-Hub-Signature-256).
  • Teams: @azure boards|pipelines|repos, @GitHub subscribe owner/repo features.

Use case: 'Is the login fix done?'

Use case comic: traceability
Figure 2.1. Use case comic: traceability

Situation. At Tailwind Traders the product manager cannot tell whether a login bug is fixed. The work item says Active, but the code was merged two days ago. Status meetings have become detective work.

StepPracticeFeature used
1Mention the work item in every commit and PRAB#123 (Azure Boards app for GitHub) or linked work items (Azure Repos)
2Require the link before mergingBranch policy Check for linked work items / a required status check
3Let the merge move the cardFixes AB#123 in the PR description; state transitions on merge
4Show the flow, not the opinionsCycle Time, Lead Time and Cumulative Flow widgets on a dashboard