|
| 1 | +--- |
| 2 | +description: 'Best practices for Azure DevOps Pipeline YAML files' |
| 3 | +applyTo: '**/azure-pipelines.yml, **/azure-pipelines*.yml, **/*.pipeline.yml' |
| 4 | +--- |
| 5 | + |
| 6 | +# Azure DevOps Pipeline YAML Best Practices |
| 7 | + |
| 8 | +## General Guidelines |
| 9 | + |
| 10 | +- Use YAML syntax consistently with proper indentation (2 spaces) |
| 11 | +- Always include meaningful names and display names for pipelines, stages, jobs, and steps |
| 12 | +- Implement proper error handling and conditional execution |
| 13 | +- Use variables and parameters to make pipelines reusable and maintainable |
| 14 | +- Follow the principle of least privilege for service connections and permissions |
| 15 | +- Include comprehensive logging and diagnostics for troubleshooting |
| 16 | + |
| 17 | +## Pipeline Structure |
| 18 | + |
| 19 | +- Organize complex pipelines using stages for better visualization and control |
| 20 | +- Use jobs to group related steps and enable parallel execution when possible |
| 21 | +- Implement proper dependencies between stages and jobs |
| 22 | +- Use templates for reusable pipeline components |
| 23 | +- Keep pipeline files focused and modular - split large pipelines into multiple files |
| 24 | + |
| 25 | +## Build Best Practices |
| 26 | + |
| 27 | +- Use specific agent pool versions and VM images for consistency |
| 28 | +- Cache dependencies (npm, NuGet, Maven, etc.) to improve build performance |
| 29 | +- Implement proper artifact management with meaningful names and retention policies |
| 30 | +- Use build variables for version numbers and build metadata |
| 31 | +- Include code quality gates (linting, testing, security scans) |
| 32 | +- Ensure builds are reproducible and environment-independent |
| 33 | + |
| 34 | +## Testing Integration |
| 35 | + |
| 36 | +- Run unit tests as part of the build process |
| 37 | +- Publish test results in standard formats (JUnit, VSTest, etc.) |
| 38 | +- Include code coverage reporting and quality gates |
| 39 | +- Implement integration and end-to-end tests in appropriate stages |
| 40 | +- Use test impact analysis when available to optimize test execution |
| 41 | +- Fail fast on test failures to provide quick feedback |
| 42 | + |
| 43 | +## Security Considerations |
| 44 | + |
| 45 | +- Use Azure Key Vault for sensitive configuration and secrets |
| 46 | +- Implement proper secret management with variable groups |
| 47 | +- Use service connections with minimal required permissions |
| 48 | +- Enable security scans (dependency vulnerabilities, static analysis) |
| 49 | +- Implement approval gates for production deployments |
| 50 | +- Use managed identities when possible instead of service principals |
| 51 | + |
| 52 | +## Deployment Strategies |
| 53 | + |
| 54 | +- Implement proper environment promotion (dev → staging → production) |
| 55 | +- Use deployment jobs with proper environment targeting |
| 56 | +- Implement blue-green or canary deployment strategies when appropriate |
| 57 | +- Include rollback mechanisms and health checks |
| 58 | +- Use infrastructure as code (ARM, Bicep, Terraform) for consistent deployments |
| 59 | +- Implement proper configuration management per environment |
| 60 | + |
| 61 | +## Variable and Parameter Management |
| 62 | + |
| 63 | +- Use variable groups for shared configuration across pipelines |
| 64 | +- Implement runtime parameters for flexible pipeline execution |
| 65 | +- Use conditional variables based on branches or environments |
| 66 | +- Secure sensitive variables and mark them as secrets |
| 67 | +- Document variable purposes and expected values |
| 68 | +- Use variable templates for complex variable logic |
| 69 | + |
| 70 | +## Performance Optimization |
| 71 | + |
| 72 | +- Use parallel jobs and matrix strategies when appropriate |
| 73 | +- Implement proper caching strategies for dependencies and build outputs |
| 74 | +- Use shallow clone for Git operations when full history isn't needed |
| 75 | +- Optimize Docker image builds with multi-stage builds and layer caching |
| 76 | +- Monitor pipeline performance and optimize bottlenecks |
| 77 | +- Use pipeline resource triggers efficiently |
| 78 | + |
| 79 | +## Monitoring and Observability |
| 80 | + |
| 81 | +- Include comprehensive logging throughout the pipeline |
| 82 | +- Use Azure Monitor and Application Insights for deployment tracking |
| 83 | +- Implement proper notification strategies for failures and successes |
| 84 | +- Include deployment health checks and automated rollback triggers |
| 85 | +- Use pipeline analytics to identify improvement opportunities |
| 86 | +- Document pipeline behavior and troubleshooting steps |
| 87 | + |
| 88 | +## Template and Reusability |
| 89 | + |
| 90 | +- Create pipeline templates for common patterns |
| 91 | +- Use extends templates for complete pipeline inheritance |
| 92 | +- Implement step templates for reusable task sequences |
| 93 | +- Use variable templates for complex variable logic |
| 94 | +- Version templates appropriately for stability |
| 95 | +- Document template parameters and usage examples |
| 96 | + |
| 97 | +## Branch and Trigger Strategy |
| 98 | + |
| 99 | +- Implement appropriate triggers for different branch types |
| 100 | +- Use path filters to trigger builds only when relevant files change |
| 101 | +- Configure proper CI/CD triggers for main/master branches |
| 102 | +- Use pull request triggers for code validation |
| 103 | +- Implement scheduled triggers for maintenance tasks |
| 104 | +- Consider resource triggers for multi-repository scenarios |
| 105 | + |
| 106 | +## Example Structure |
| 107 | + |
| 108 | +```yaml |
| 109 | +# azure-pipelines.yml |
| 110 | +trigger: |
| 111 | + branches: |
| 112 | + include: |
| 113 | + - main |
| 114 | + - develop |
| 115 | + paths: |
| 116 | + exclude: |
| 117 | + - docs/* |
| 118 | + - README.md |
| 119 | + |
| 120 | +variables: |
| 121 | + - group: shared-variables |
| 122 | + - name: buildConfiguration |
| 123 | + value: 'Release' |
| 124 | + |
| 125 | +stages: |
| 126 | + - stage: Build |
| 127 | + displayName: 'Build and Test' |
| 128 | + jobs: |
| 129 | + - job: Build |
| 130 | + displayName: 'Build Application' |
| 131 | + pool: |
| 132 | + vmImage: 'ubuntu-latest' |
| 133 | + steps: |
| 134 | + - task: UseDotNet@2 |
| 135 | + displayName: 'Use .NET SDK' |
| 136 | + inputs: |
| 137 | + version: '8.x' |
| 138 | + |
| 139 | + - task: DotNetCoreCLI@2 |
| 140 | + displayName: 'Restore dependencies' |
| 141 | + inputs: |
| 142 | + command: 'restore' |
| 143 | + projects: '**/*.csproj' |
| 144 | + |
| 145 | + - task: DotNetCoreCLI@2 |
| 146 | + displayName: 'Build application' |
| 147 | + inputs: |
| 148 | + command: 'build' |
| 149 | + projects: '**/*.csproj' |
| 150 | + arguments: '--configuration $(buildConfiguration) --no-restore' |
| 151 | + |
| 152 | + - stage: Deploy |
| 153 | + displayName: 'Deploy to Staging' |
| 154 | + dependsOn: Build |
| 155 | + condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) |
| 156 | + jobs: |
| 157 | + - deployment: DeployToStaging |
| 158 | + displayName: 'Deploy to Staging Environment' |
| 159 | + environment: 'staging' |
| 160 | + strategy: |
| 161 | + runOnce: |
| 162 | + deploy: |
| 163 | + steps: |
| 164 | + - download: current |
| 165 | + displayName: 'Download drop artifact' |
| 166 | + artifact: drop |
| 167 | + - task: AzureWebApp@1 |
| 168 | + displayName: 'Deploy to Azure Web App' |
| 169 | + inputs: |
| 170 | + azureSubscription: 'staging-service-connection' |
| 171 | + appType: 'webApp' |
| 172 | + appName: 'myapp-staging' |
| 173 | + package: '$(Pipeline.Workspace)/drop/**/*.zip' |
| 174 | +``` |
| 175 | +
|
| 176 | +## Common Anti-Patterns to Avoid |
| 177 | +
|
| 178 | +- Hardcoding sensitive values directly in YAML files |
| 179 | +- Using overly broad triggers that cause unnecessary builds |
| 180 | +- Mixing build and deployment logic in a single stage |
| 181 | +- Not implementing proper error handling and cleanup |
| 182 | +- Using deprecated task versions without upgrade plans |
| 183 | +- Creating monolithic pipelines that are difficult to maintain |
| 184 | +- Not using proper naming conventions for clarity |
| 185 | +- Ignoring pipeline security best practices |
0 commit comments