azure-pipelines

验证 Azure Pipeline 更改

修改 Azure DevOps Pipeline 文件（build/azure-pipelines/ 中的 YAML 文件）时，可以在提交前使用 Azure CLI 在本地验证更改。这样可以避免缓慢的反馈循环：推送更改、等待 CI，然后检查结果。

先决条件

1. 检查是否已安装 Azure CLI：

   az --version
   

   如果尚未安装，请安装：

   # macOS
   brew install azure-cli
   
   # Windows (PowerShell as Administrator)
   winget install Microsoft.AzureCLI
   
   # Linux (Debian/Ubuntu)
   curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
   

2. 检查是否已安装 DevOps 扩展：

   az extension show --name azure-devops
   

   如果尚未安装，请添加：

   az extension add --name azure-devops
   

3. 进行身份验证：

   az login
   az devops configure --defaults organization=https://dev.azure.com/monacotools project=Monaco
   

VS Code 主构建

VS Code 主构建 Pipeline：

• 组织：monacotools
• 项目：Monaco
• 定义 ID：111
• URL：https://dev.azure.com/monacotools/Monaco/_build?definitionId=111

VS Code Insider 定时构建

每天会按计划自动运行两个 Insider 构建：

• 早间构建：约欧洲中部时间上午 7:00
• 晚间构建：约欧洲中部时间晚上 7:00

这些定时构建使用相同的 Pipeline 定义（111），但会在 main 分支上运行，以生成 Insider 版本。

---

排队构建

使用排队命令排队运行验证构建：

# Queue a build on the current branch
node .github/skills/azure-pipelines/azure-pipeline.ts queue

# Queue with a specific source branch
node .github/skills/azure-pipelines/azure-pipeline.ts queue --branch my-feature-branch

# Queue with custom parameters
node .github/skills/azure-pipelines/azure-pipeline.ts queue --parameter "VSCODE_BUILD_WEB=false" --parameter "VSCODE_PUBLISH=false"

# Parameter value with spaces
node .github/skills/azure-pipelines/azure-pipeline.ts queue --parameter "VSCODE_BUILD_TYPE=Product Build"

重要：排队运行新构建前，请取消同一分支上不再需要的任何先前构建。这样可以释放构建 Agent 并减少资源浪费：

# 从状态中找到构建 ID，然后取消该构建
node .github/skills/azure-pipelines/azure-pipeline.ts status
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id <id>
node .github/skills/azure-pipelines/azure-pipeline.ts queue

脚本选项

选项	说明
--branch <name>	要构建的源分支（默认：当前 git 分支）
--definition <id>	Pipeline 定义 ID（默认：111）
--parameter <entry>	KEY=value 格式的 Pipeline 参数（可重复）；值包含空格时请使用此选项
--parameters <list>	以空格分隔的 KEY=value KEY2=value2 格式参数；值不得包含空格
--dry-run	打印命令但不执行

产品构建队列参数 (build/azure-pipelines/product-build.yml)

名称	类型	默认值	允许的值	描述
VSCODE_QUALITY	字符串	insider	exploration、insider、stable	构建质量通道
VSCODE_BUILD_TYPE	字符串	Product Build	Product、CI	产品构建或 CI 的构建模式
NPM_REGISTRY	字符串	https://pkgs.dev.azure.com/monacotools/Monaco/_packaging/vscode/npm/registry/	任意 URL	自定义 npm 注册表
CARGO_REGISTRY	字符串	sparse+https://pkgs.dev.azure.com/monacotools/Monaco/_packaging/vscode/Cargo/index/	任意 URL	自定义 Cargo 注册表
VSCODE_BUILD_WIN32	布尔值	true	true、false	构建 Windows x64
VSCODE_BUILD_WIN32_ARM64	布尔值	true	true、false	构建 Windows arm64
VSCODE_BUILD_LINUX	布尔值	true	true、false	构建 Linux x64
VSCODE_BUILD_LINUX_SNAP	布尔值	true	true、false	构建 Linux x64 Snap
VSCODE_BUILD_LINUX_ARM64	布尔值	true	true、false	构建 Linux arm64
VSCODE_BUILD_LINUX_ARMHF	布尔值	true	true、false	构建 Linux armhf
VSCODE_BUILD_ALPINE	布尔值	true	true、false	构建 Alpine x64
VSCODE_BUILD_ALPINE_ARM64	布尔值	true	true、false	构建 Alpine arm64
VSCODE_BUILD_MACOS	布尔值	true	true、false	构建 macOS x64
VSCODE_BUILD_MACOS_ARM64	布尔值	true	true、false	构建 macOS arm64
VSCODE_BUILD_MACOS_UNIVERSAL	布尔值	true	true、false	构建 macOS 通用版本（需要 macOS 的两种架构）
VSCODE_BUILD_WEB	布尔值	true	true、false	构建 Web 构件
VSCODE_PUBLISH	布尔值	true	true、false	发布到 builds.code.visualstudio.com
VSCODE_RELEASE	布尔值	false	true、false	成功后触发发布流程
VSCODE_STEP_ON_IT	布尔值	false	true、false	跳过测试
VSCODE_USE_LEGACY_OSS_NOTICE	布尔值	false	true、false	保留旧版混合的 ThirdPartyNotices.txt，而不使用 Component Governance 声明

示例：运行一次面向 CI 的快速验证，尽量减少发布相关的副作用：

node .github/skills/azure-pipelines/azure-pipeline.ts queue \
   --parameter "VSCODE_BUILD_TYPE=CI Build" \
   --parameter "VSCODE_PUBLISH=false" \
   --parameter "VSCODE_RELEASE=false"

---

检查构建状态

使用状态命令监控正在运行的构建：

# Get status of the most recent builds
node .github/skills/azure-pipelines/azure-pipeline.ts status

# Get overview of a specific build by ID
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id 123456

# Watch build status (refreshes every 30 seconds)
node .github/skills/azure-pipelines/azure-pipeline.ts status --watch

# Watch with custom interval (60 seconds)
node .github/skills/azure-pipelines/azure-pipeline.ts status --watch 60

脚本选项

选项	描述
--build-id <id>	指定构建 ID（默认值：当前分支上最近的一次构建）
--branch <name>	按分支名称筛选构建（显示该分支最近的 20 次构建）
--reason <reason>	按原因筛选构建：manual、individualCI、batchedCI、schedule、pullRequest
--definition <id>	流水线定义 ID（默认值：111）
--watch [seconds]	持续轮询状态，直到构建完成（默认值：30s）
--download-log <id>	将指定日志下载到 /tmp
--download-artifact <name>	将构件下载到 /tmp
--json	输出原始 JSON，以供程序处理

---

取消构建

使用取消命令停止正在运行的构建：

# Cancel a build by ID (use status command to find IDs)
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id 123456

# Dry run (show what would be cancelled)
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id 123456 --dry-run

脚本选项

选项	描述
--build-id <id>	要取消的构建 ID（必需）
--definition <id>	流水线定义 ID（默认值：111）
--dry-run	输出将要取消的内容，但不执行操作

---

测试流水线更改

当用户要求测试 Azure Pipelines 构建中的更改时，请按照以下工作流程操作：

1. 在当前分支上排队一个新构建
2. 轮询直至完成，定期检查构建状态，直到构建结束

轮询构建完成状态

使用带有 sleep 的 shell 循环轮询构建状态。sleep 命令适用于所有主流操作系统：

# Queue the build and note the build ID from output (e.g., 123456)
node .github/skills/azure-pipelines/azure-pipeline.ts queue

# Poll every 60 seconds until complete (works on macOS, Linux, and Windows with Git Bash/WSL)
# Replace <BUILD_ID> with the actual build ID from the queue command
while true; do
  node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id <BUILD_ID> --json 2>/dev/null | grep -q '"status": "completed"' && break
  sleep 60
done

# Check final result
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id <BUILD_ID>

或者，使用内置的 --watch 标志自动轮询：

node .github/skills/azure-pipelines/azure-pipeline.ts queue
# Use the build ID returned by the queue command
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id <BUILD_ID> --watch

注意：--watch 标志默认每隔 30 秒轮询一次。使用 --watch 60 可将间隔设为 60 秒，以减少 API 调用。

---

常见工作流

1. 快速验证流水线

# Make your YAML changes, then:
git add -A && git commit -m "test: pipeline changes"
git push origin HEAD

# Check for any previous builds on this branch and cancel if needed
node .github/skills/azure-pipelines/azure-pipeline.ts status
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id <id>  # if there's an active build

# Queue and watch the new build
node .github/skills/azure-pipelines/azure-pipeline.ts queue
node .github/skills/azure-pipelines/azure-pipeline.ts status --watch

2. 调查构建

# Get overview of a build (shows stages, artifacts, and log IDs)
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id 123456

# Download a specific log for deeper inspection
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id 123456 --download-log 5

# Download an artifact
node .github/skills/azure-pipelines/azure-pipeline.ts status --build-id 123456 --download-artifact unsigned_vscode_cli_win32_x64_cli

3. 使用修改后的参数进行测试

# Customize build matrix for quicker validation
node .github/skills/azure-pipelines/azure-pipeline.ts queue \
   --parameter "VSCODE_BUILD_TYPE=CI Build" \
   --parameter "VSCODE_BUILD_WEB=false" \
   --parameter "VSCODE_BUILD_ALPINE=false" \
   --parameter "VSCODE_BUILD_ALPINE_ARM64=false" \
   --parameter "VSCODE_PUBLISH=false"

4. 取消正在运行的构建

# First, find the build ID
node .github/skills/azure-pipelines/azure-pipeline.ts status

# Cancel a specific build by ID
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id 123456

# Dry run to see what would be cancelled
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id 123456 --dry-run

5. 迭代流水线变更

迭代修改流水线 YAML 时，始终先取消过时的构建，再将新构建加入队列：

# Push new changes
git add -A && git commit --amend --no-edit
git push --force-with-lease origin HEAD

# Find the outdated build ID and cancel it
node .github/skills/azure-pipelines/azure-pipeline.ts status
node .github/skills/azure-pipelines/azure-pipeline.ts cancel --build-id <id>

# Queue a fresh build and monitor
node .github/skills/azure-pipelines/azure-pipeline.ts queue
node .github/skills/azure-pipelines/azure-pipeline.ts status --watch

---

故障排除

身份验证问题

# Re-authenticate
az logout
az login

# Check current account
az account show

找不到扩展

az extension add --name azure-devops --upgrade

速率限制

如果遇到速率限制，请在 API 调用之间添加延迟，或使用间隔更长的 --watch。