ado-pipeline-best-practices

Azure Pipelines 最佳实践

创建和维护 Azure DevOps YAML 管道的全面最佳实践。

核心审查流程

1. 在编辑 YAML 前，确定触发器范围、部署环境和所需审批。
2. 验证机密是否通过服务连接、Key Vault、机密变量或安全文件传递；切勿将凭据直接写入 YAML。
3. 固定任务主版本，并将重复步骤集中到模板中。
4. 仅在路径筛选、缓存和并行作业确实能降低构建成本且不会掩盖验证时才添加它们。
5. 通过阶段或作业将构建、测试、打包和部署职责分开。
6. 在建议 rollout 前，使用 Azure DevOps 管道 YAML 验证或试运行进行验证。

管道结构

多阶段管道：

# Recommended structure
stages:
  - stage: Build
  - stage: Test
  - stage: DeployDev
  - stage: DeployStaging  
  - stage: DeployProduction

优势：

• 清晰划分职责
• 按条件执行阶段
• 针对不同环境进行配置
• 在阶段之间设置审批门禁

触发器和计划

最佳实践：

• 使用路径筛选，避免不必要的构建
• 为高频提交的仓库启用批量构建
• 使用 PR 触发器进行验证
• 安排每晚／每周构建，进行全面测试

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

变量管理

层级：

1. 管道级变量（az devops YAML）
2. 变量组（在多个管道间共享）
3. Azure Key Vault（机密）
4. 运行时参数（用户输入）

安全性：

• 切勿硬编码机密
• 使用 Key Vault 存储敏感数据
• 在变量组中将变量标记为机密
• 日志中的机密会自动屏蔽

缓存

为以下内容实施缓存：

• 包依赖（npm、pip、NuGet、Maven）
• Docker 层
• 构建输出

效果：

• 加快构建速度（最多可缩短 90%）
• 减少网络使用量
• 降低成本

模板

将模板用于：

• 可复用的构建模式
• 标准化的部署步骤
• 一致的安全扫描
• 全公司适用的最佳实践

优势：

• DRY（不要重复自己）
• 集中更新
• 流程一致

安全实践

必备项：

• 代码扫描（SAST、依赖项）
• 容器镜像扫描
• 机密扫描
• 合规性检查
• 分支保护策略
• 必需的审批

性能

优化方式：

• 并行运行彼此独立的作业
• 充分利用缓存
• 使用浅克隆 Git（fetchDepth: 1）
• 选择合适的 Agent 池
• 清理构建产物

监控

跟踪：

• 构建成功率
• 构建时长
• 测试通过率
• 部署频率
• 平均恢复时间（MTTR）

参考资料和搭配指南

• 使用 Microsoft Azure Pipelines YAML 架构文档，了解任务语法和新发布的功能。
• 替换服务主体机密时，搭配使用工作负载身份／OIDC 指南。
• 添加 SAST、依赖项、容器或 IaC 检查时，搭配使用安全扫描指南。

务必根据最新的 Azure DevOps 文档核实最佳实践。