Azure DevOps Cheatsheet: From Boards to Pipelines

Azure DevOps Best Practices

The rules that separate a healthy Azure DevOps setup from an expensive mess. Every policy and check name below is current on Microsoft Learn as of July 2026. If you only adopt one section of this cheatsheet, adopt this one.

Branch Policies & PR Gates

Protect main with policy, not etiquette. A protected branch cannot be pushed to directly; every change arrives through a pull request that must clear the gates you configure.

The policies worth turning on:

Require a minimum number of reviewers: set 1–2; enable "reset approvals on new pushes" so a re-review is forced after changes, and block self-approval.
Require linked work items: guarantees every commit traces back to a Board item.
Require comment resolution: a PR cannot complete while review comments are still open.
Build validation: link the CI pipeline; the PR is blocked unless it builds and tests pass. This is your first hard quality gate.
Status checks: require external signals (SonarQube quality gate, security scan) to report success before merge.
Limit merge types: standardize on squash or rebase to keep main history linear and readable.
Automatically include reviewers: auto-add the owning team via path filters so the right eyes always see the change.

Anti-pattern: granting "bypass policies when completing pull requests" broadly. Reserve bypass for a tiny break-glass group and audit its use.

Pipeline Security

Your pipeline runs with credentials and touches production. Treat it as a privileged system, not a build script. Most breaches here come from long-lived secrets and over-scoped permissions.

Hardening checklist:

Workload identity federation: replace secret-based Azure service connections with federated (OIDC) connections so there is no stored secret to leak or rotate.
Secrets in Key Vault only: reference them through a variable group linked to Key Vault; never store secrets in YAML or plaintext variables. Secret variables are masked in logs.
Protect shared resources: put approvals and checks on service connections, agent pools, and variable groups, not just environments, so a rogue pipeline cannot borrow them.
Scope the token: set the job authorization scope to project (not collection) and grant the build service the least access it needs.
Pin and scan: pin task and container image versions; run SAST/SCA (GHAzDO CodeQL, dependency scanning) as a required check.
Guard pull_request triggers: do not expose secrets to pipelines triggered by forks or untrusted contributors.

Environments, Approvals & Checks

Model each deployment target (Dev, QA, Prod) as an Azure Pipelines environment, then attach approvals and checks. This is how you get manual gates, deployment history, and blast-radius control.

The checks you can stack on an environment:

Approvals: require named people or groups to sign off before the stage runs; approvers cannot be the person who queued the run.
Branch control: only allow deployment from an approved branch such as main.
Business hours: defer production deploys to a safe window.
Invoke REST API / Azure Function: call an external gate (change management, test results) and pass only on success.
Query Azure Monitor alerts: block promotion if the target is currently unhealthy.
Required template & evaluate artifact: enforce that the pipeline extends an approved template and that artifacts meet policy.
Exclusive lock: serialize deployments so two runs cannot hit the same environment at once.

Continuous Delivery vs Deployment: Delivery = automatic to a staging environment, human approval to prod. Deployment = automatic all the way to prod. Choose per service; do not default every service to fully automatic prod without strong test coverage.

Work-Item Hygiene & Traceability

The value of Boards is end-to-end traceability: idea → work item → branch → PR → build → release. That chain only exists if the team keeps items honest and linked.

Practices that keep Boards trustworthy:

One backlog, prioritized: a single ordered product backlog beats five personal to-do lists. Rank ruthlessly.
Definition of Done: encode it on the board (tests, docs, review) so "done" means the same thing to everyone.
Area & iteration paths: configure them up front; they drive team assignment, sprint scoping, and every velocity report.
WIP limits: cap in-progress columns to expose bottlenecks instead of hiding them.
Link everything: enforce work-item linking via branch policy (above) so traceability is automatic, not aspirational.
Right-size items: a User Story should fit inside a sprint; anything bigger is a Feature that needs splitting.

Infrastructure-as-Code Gates

Infrastructure changes are the highest-blast-radius thing a pipeline does. Gate them harder than application code: a human should see exactly what will change before it changes.

The safe IaC pipeline shape:

Plan then approve then apply: terraform plan (or bicep what-if) publishes an artifact; a manual approval on the environment gates terraform apply against that exact plan.
Remote state with locking: store tfstate in an Azure Storage backend; locking prevents two runs from corrupting it. Never keep state on a local disk.
Least-privilege deploy identity: the IaC service connection gets only the roles it needs on the target subscription, scoped per environment.
Policy as code: run Azure Policy / OPA / tfsec checks as required status checks so non-compliant infra fails the PR.
No portal drift: ban manual changes in the Azure Portal; reconcile drift by re-running the pipeline, not by clicking.

Pipeline Reliability & Speed

A slow, flaky pipeline gets bypassed, and a bypassed pipeline protects nothing. Keep CI fast and deterministic so the team trusts the gates instead of routing around them.

Keep it fast and boring:

YAML pipelines only: versioned, reviewed, and diffable. The classic UI editor is unversioned click-ops; migrate off it.
Reusable templates: factor shared steps into templates so 30 pipelines change in one place.
Cache dependencies: use the Cache task for NuGet/npm to cut minutes off every run.
Fail fast, run in parallel: split independent jobs; put the cheapest checks (lint, unit) first.
Quarantine flaky tests: a test that fails randomly trains people to hit re-run. Fix or isolate it.
Set retention: configure artifact and run retention so storage and noise do not grow without bound.

Agile Planning & Work Management

Azure Boards

If you don't plan your work, you plan to fail. Azure Boards is the central hub for work item tracking, backlogs, and sprint planning. It's where all work should originate.

Core Components:

Work Items: The fundamental units of work (e.g., User Story, Bug, Task).
Backlogs: A prioritized list of work items. You'll have product backlogs (all work) and sprint backlogs (work for the current iteration).
Boards: Kanban-style visualization of your workflow. Customize columns to match your team's process.
Sprints/Iterations: Time-boxed periods where a team commits to a set of work.

Best Practice: Traceability

Your mantra: "If it's not in Boards, it doesn't exist." Every commit, branch, and pull request must be linked to a work item. This provides end-to-end traceability from idea to deployment.

Why It's Non-Negotiable:

Context: Understand *why* a change was made, directly from the code.
Auditing: Easily track all changes related to a specific feature or bug fix.
Automation: Use branch policies to enforce work item linking on all pull requests.
Reporting: Generate accurate reports on team velocity, cycle time, and project status.

Critical Rule: Configure your `main` branch policy to "Check for linked work items." This is the simplest and most effective process improvement you can make.

Source Control Management

Azure Repos

The foundation of your pipeline. It's Git. Don't overthink it. If your code is in TFVC, your top priority is migrating. No excuses.

Core Principle:

This is your single source of truth. All changes—code, configuration, pipelines, infrastructure—must live here. Protect it accordingly.

Tooling:

Azure Repos: It's a perfectly functional Git host that integrates tightly with the rest of Azure DevOps.
Git: The undisputed standard for version control. Anything else is a historical artifact and technical debt.

Best Practice: Branch Policies

Policies are non-negotiable. Protect your `main` branch like it's the last bastion of sanity. Automate your Pull Requests to enforce quality gates from the very start.

Mandatory Policies for `main`:

Require a minimum number of reviewers: No developer merges their own code without a second pair of eyes.
Check for linked work items: Every change must be traceable to a requirement or bug.
Check for comment resolution: Ensure all review feedback is addressed.
Enforce Build Validation: Link your CI pipeline here. If the PR doesn't build and pass tests, it's blocked. This is your first quality gate.

Continuous Integration

Azure Pipelines (YAML ONLY)

Your pipeline is code. Treat it like code. Do NOT use the "classic" UI editor. It creates a click-ops nightmare that is impossible to version, review, or scale.

Core Principle:

Define your build pipeline as an `azure-pipelines.yml` file, committed to the root of your repository. This ensures your pipeline is versioned alongside your code.

Best Practices:

Use Templates: For common, reusable steps, create pipeline templates. This standardizes your process and makes maintenance trivial.
Use Variable Groups: For shared variables and secrets. Link them to Azure Key Vault.

SonarQube Integration

SonarQube is your automated code reviewer. Integrate it into CI and fail the build if the quality gate is not met.

Typical CI Pipeline Steps with SonarQube:

Prepare Analysis: Connects to your SonarQube server.
Run Build & Tests: Compile code and generate code coverage reports.
Run Code Analysis: Sonar scanner analyzes code and coverage reports.
Publish Quality Gate Result: Polls SonarQube and checks the Quality Gate status.

Critical Rule: Configure the "Publish Quality Gate Result" task to fail the build if the gate fails.

CI Key Stages

The moment code is merged, it must be built, tested, and packaged. The goal is to catch errors early and often, before they reach production.

Mandatory Stages:

Build: Compile the code. If it doesn't build, it's broken.
Test: Run unit and integration tests.
Scan: Perform security and quality scans (e.g., SonarQube, SAST, SCA).
Package: Create a deployable artifact (e.g., a Docker image ).

Quality Assurance & Test Management

Azure Test Plans

Automated tests are essential but don't cover everything. Use Azure Test Plans for manual, exploratory, and user acceptance testing (UAT) to ensure comprehensive quality.

Key Features:

Test Plans & Suites: Group test cases into logical suites. Requirement-based suites automatically link test cases to user stories in Boards.
Test Case Management: Define detailed, step-by-step manual test cases with expected results.
Web-based Test Runner: Execute tests directly in the browser, marking steps as pass/fail and capturing screenshots or recordings.
Exploratory Testing: Capture rich data (notes, screenshots, HAR files) during unscripted testing sessions.

End-to-End Traceability

Linking test results back to requirements is critical for quality reporting. Test Plans creates a full audit trail, showing which tests validate which features and what their latest outcomes are.

How It Connects:

Failing a manual test step can automatically create a bug in Azure Boards, pre-populated with repro steps and system info.
Test results from automated CI/CD pipeline runs can be published to Test Plans, providing a single view of both manual and automated test quality.
Stakeholders can view the "Test" tab on a work item to see all associated test cases and their results, providing confidence before deployment.

Package Management

Azure Artifacts

Manage your dependencies. Azure Artifacts provides private, secure feeds for hosting packages like NuGet, npm, Maven, Python, Cargo, and Universal Packages. Stop relying solely on public registries.

Why Use It?

Reliability: Cache upstream packages. If a public registry goes down or a package is unpublished, your builds won't break.
Security: Control what packages your organization uses. Share private packages securely across teams.
Integration: Seamlessly integrated with Azure Pipelines for publishing and restoring packages.

Feeds and Views

Don't just dump packages into a single feed. Use views (`@local`, `@prerelease`, `@release`) to promote packages through different quality rings, just like you do with your code.

Release Flow with Views:

CI build publishes a new package version to the `@local` view.
Automated tests run against the `@local` view.
If tests pass, the pipeline promotes the package to the `@prerelease` view for broader integration testing.
After validation, a release pipeline promotes the package to the `@release` view, making it available for production use.

Infrastructure as Code

Terraform

Your infrastructure must be defined as code. Manual configuration in the Azure Portal is a recipe for disaster. Terraform is the industry standard.

Why Terraform?

While Microsoft pushes Bicep/ARM, Terraform is cloud-agnostic and its `plan` command is a lifesaver for preventing accidental changes.

The Holy Trinity of Terraform Commands in a Pipeline:

terraform init : Initializes the backend and providers.
terraform plan : Shows exactly what will change. This step must create a plan artifact that requires manual approval.
terraform apply : Executes the approved plan.

Terraform Remote State

The biggest mistake teams make with Terraform is storing the `terraform.tfstate` file locally. Always use a remote backend like an Azure Storage Account.

Why Remote State is Critical:

Collaboration: Allows multiple team members to work on the same infrastructure.
State Locking: Prevents concurrent runs from corrupting the state file.
Security: The state file can contain secrets. Storing it in a secured storage account is essential.

Continuous Delivery/Deployment

Azure Pipelines (Releases)

Automating your release is the whole point. Release Pipelines offer better visualization of your environments and crucial manual approval gates for production.

Release Pipeline Structure:

Artifacts: Triggered by a new build artifact (e.g., Docker image, Terraform plan).
Stages: Create a stage for each environment (e.g., Dev, QA, Prod).
Approval Gates: Use automated gates (smoke tests) and manual gates (human approval) to control promotion between stages.

Key Deployment Concepts

Differentiate between Continuous Delivery (manual deploy to prod) and Continuous Deployment (automatic to prod). Use deployment strategies to limit blast radius.

Immutable Infrastructure: Don't modify running servers. Replace them with fresh ones built from your artifacts.
Blue/Green or Canary Deployments: Deploy to a subset of users (Canary) or a parallel environment (Blue/Green) before a full rollout.

Security

Key Security Practices (Shift Left)

Security is not a separate step; it's a part of every step. Embed automated security checks into your pipeline to catch vulnerabilities early.

Pipeline Integration Points:

SAST : Analyze source code. SonarQube has SAST capabilities. GitHub Advanced Security for Azure DevOps (GHAzDO) adds CodeQL-powered code scanning, secret scanning, and dependency scanning natively in Azure Repos. CodeQL default setup (one-click enablement) is now generally available as of July 2026; buildless scanning via `buildtype: none` is available in advanced setup.
SCA : Scan open-source dependencies for known vulnerabilities. GHAzDO includes dependency scanning for this purpose.
Container Scanning: Scan your Docker images for vulnerabilities.

Secret Management: Azure Key Vault

Don't put secrets in your code, variable groups, or YAML files. This is amateur hour. Use Azure Key Vault.

The Only Acceptable Way:

Store all secrets in Azure Key Vault. In your Pipeline, use a Variable Group linked to the Key Vault. Secrets will be fetched at runtime and masked in logs.

Critical Rule: Developers should not have direct access to production secrets. The pipeline is the only entity that should fetch and use them in production.

Monitoring & Observability

The Three Pillars

If you're not monitoring your application in production, you're flying blind. Observability is understanding your system's state from the outside.

Logging: Records of discrete events. Use structured logging.
Metrics: Aggregated, time-series data on key performance indicators (e.g., CPU, latency).
Tracing: Track a single request as it moves through your distributed system.

Azure Tooling

Use the integrated Azure tools. They're not always best-in-class, but their deep integration simplifies your life immensely.

Recommended Azure Stack:

Azure Monitor: The umbrella service for metrics and basic logging.
Application Insights: The APM solution. Instrument your code with its SDK to get rich logging, dependency tracking, and distributed tracing.
Log Analytics Workspace: The destination for all your logs. Use Kusto Query Language (KQL) to query everything.