ado-pipeline-best-practices
Azure DevOps pipeline best practices, patterns, and industry standards
When & Why to Use This Skill
This Claude skill provides expert guidance on Azure DevOps pipeline best practices, offering standardized patterns for YAML configurations, security hardening, and performance optimization. It helps developers and DevOps engineers build scalable, secure, and efficient CI/CD workflows using industry-standard multi-stage architectures.
Use Cases
- Architecting multi-stage YAML pipelines to implement clear separation of concerns and environment-specific deployment gates.
- Optimizing build performance and reducing costs by implementing dependency caching and parallel job execution.
- Securing CI/CD processes through Azure Key Vault integration, secret masking, and automated security scanning patterns.
- Configuring advanced trigger strategies and PR validation policies to ensure code quality and reduce unnecessary build cycles.
- Standardizing organizational DevOps processes using reusable YAML templates for consistent build and deployment patterns.
| name | ado-pipeline-best-practices |
|---|---|
| description | Azure DevOps pipeline best practices, patterns, and industry standards |
🚨 CRITICAL GUIDELINES
Windows File Path Requirements
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).
Examples:
- ❌ WRONG:
D:/repos/project/file.tsx - ✅ CORRECT:
D:\repos\project\file.tsx
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
Documentation Guidelines
NEVER create new documentation files unless explicitly requested by the user.
- Priority: Update existing README.md files rather than creating new documentation
- Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
- Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
- User preference: Only create additional .md files when user specifically asks for documentation
Azure Pipelines Best Practices
Comprehensive best practices for creating and maintaining Azure DevOps YAML pipelines.
Pipeline Structure
Multi-Stage Pipelines:
# Recommended structure
stages:
- stage: Build
- stage: Test
- stage: DeployDev
- stage: DeployStaging
- stage: DeployProduction
Benefits:
- Clear separation of concerns
- Conditional stage execution
- Environment-specific configurations
- Approval gates between stages
Triggers and Scheduling
Best practices:
- Use path filters to avoid unnecessary builds
- Enable batch builds for high-frequency repos
- Use PR triggers for validation
- Schedule nightly/weekly builds for comprehensive testing
trigger:
batch: true
branches:
include: [main, develop]
paths:
exclude: ['docs/*', '**.md']
pr:
autoCancel: true
branches:
include: [main]
schedules:
- cron: '0 0 * * *'
displayName: 'Nightly build'
branches:
include: [main]
always: false # Only if code changed
Variable Management
Hierarchy:
- Pipeline-level variables (az devops YAML)
- Variable groups (shared across pipelines)
- Azure Key Vault (secrets)
- Runtime parameters (user input)
Security:
- Never hardcode secrets
- Use Key Vault for sensitive data
- Mark secrets in variable groups
- Secrets are automatically masked in logs
Caching
Implement caching for:
- Package dependencies (npm, pip, NuGet, Maven)
- Docker layers
- Build outputs
Impact:
- Faster builds (up to 90% reduction)
- Reduced network usage
- Lower costs
Templates
Use templates for:
- Reusable build patterns
- Standardized deployment steps
- Consistent security scanning
- Company-wide best practices
Benefits:
- DRY (Don't Repeat Yourself)
- Centralized updates
- Consistent processes
Security Practices
Essential:
- Code scanning (SAST, dependency)
- Container image scanning
- Secret scanning
- Compliance checks
- Branch protection policies
- Required approvals
Performance
Optimize:
- Parallelize independent jobs
- Use caching extensively
- Shallow git clones (fetchDepth: 1)
- Appropriate agent pools
- Clean up artifacts
Monitoring
Track:
- Build success rates
- Build durations
- Test pass rates
- Deployment frequency
- Mean time to recovery (MTTR)
Always verify best practices against latest Azure DevOps documentation.