Ado Operation

Azure DevOps Operations

Azure CLI (az devops) を主軸に Azure DevOps を操作するスキル。 専用コマンドがない操作は az devops invoke (REST API ラッパー) で補完する。

IMPORTANT: Windows 日本語文字化け防止

Azure CLI (MSI版) は内蔵 Python を -I (isolated mode) で起動するため、 PYTHONUTF8=1 や PYTHONIOENCODING 等の環境変数は無効。 出力は常に cp932 (Shift-JIS) となるため、全ての az コマンドの末尾に 2>&1 | iconv -f cp932 -t utf-8 を付与すること。

# NG: 日本語が文字化けする
az boards work-item show --id 123 --output table

# OK: iconv で UTF-8 に変換
az boards work-item show --id 123 --output table 2>&1 | iconv -f cp932 -t utf-8

このルールは本スキル内の全コマンドに適用する。

コマンド体系

az devops invoke が必要な操作

以下は専用コマンドがないため az devops invoke で対応する:

• PR コメント・スレッド -- 取得・追加・インラインコメント・ステータス更新
• ビルドタイムライン -- ステージ・ジョブ・タスクの詳細と失敗箇所特定
• テスト結果 -- テスト実行結果・失敗テストの詳細
• 添付ファイル -- Work Item への添付アップロード・リンク
• Git 差分 -- コミット間差分・PR 変更ファイル一覧
• 通知 -- サブスクリプション管理

詳細は references/rest-api.md を参照。

MCP (オプション)

Azure DevOps MCP Server (@azure-devops/mcp) が設定済みの場合、MCP ツールも利用可能。 機能的に CLI と同等だが、構造化データを直接取得できるため効率的な場合がある。

MCP セットアップ: ~/.claude/settings.json の mcpServers に追加:

"azure-devops": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@azure-devops/mcp", "{ORG_NAME}"]
}

Prerequisites

# Login check
az account show 2>&1 | iconv -f cp932 -t utf-8

# DevOps extension check
az extension show --name azure-devops 2>&1 | iconv -f cp932 -t utf-8

# Organization default setting (recommend)
az devops configure --defaults organization=https://dev.azure.com/{ORG}
az devops configure --defaults project={PROJECT}

Core Workflow

1. Work Items

詳細は references/work-items.md を参照。

# 作成
az boards work-item create --type "Task" --title "タスク名" \
  --assigned-to "user@example.com" --description "詳細" 2>&1 | iconv -f cp932 -t utf-8

# 表示
az boards work-item show --id {ID} --output table 2>&1 | iconv -f cp932 -t utf-8

# 更新
az boards work-item update --id {ID} --state "Active" \
  --assigned-to "user@example.com" 2>&1 | iconv -f cp932 -t utf-8

# WIQL クエリ
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] \
  FROM WorkItems WHERE [System.AssignedTo] = @Me \
  AND [System.State] <> 'Closed' \
  ORDER BY [System.ChangedDate] DESC" --output table 2>&1 | iconv -f cp932 -t utf-8

2. Pull Requests

詳細は references/pull-requests.md を参照。

# PR 作成
az repos pr create --source-branch "feature/xxx" --target-branch "main" \
  --title "タイトル" --description "説明" 2>&1 | iconv -f cp932 -t utf-8

# PR 一覧
az repos pr list --status active --output table 2>&1 | iconv -f cp932 -t utf-8

# レビュー投票 (approve=10, approve-with-suggestions=5, wait-for-author=-5, reject=-10)
az repos pr set-vote --id {PR_ID} --vote approve 2>&1 | iconv -f cp932 -t utf-8

# PR コメント取得 (az devops invoke)
# NOTE: --resource には REST API パス名ではなく CLI 内部の resource 名を使う
az devops invoke --area git --resource pullRequestThreads \
  --route-parameters project={PROJECT} repositoryId={REPO_ID} pullRequestId={PR_ID} \
  --http-method GET --api-version "7.1" 2>&1 | iconv -f cp932 -t utf-8

3. Pipelines

詳細は references/pipelines.md を参照。

# パイプライン一覧
az pipelines list --output table 2>&1 | iconv -f cp932 -t utf-8

# 実行
az pipelines run --name "pipeline-name" --branch "main" 2>&1 | iconv -f cp932 -t utf-8

# ビルド状態確認
az pipelines build show --id {BUILD_ID} --output table 2>&1 | iconv -f cp932 -t utf-8

# ビルドタイムライン (az devops invoke)
az devops invoke --area build --resource timeline \
  --route-parameters project={PROJECT} buildId={BUILD_ID} \
  --api-version "7.1" 2>&1 | iconv -f cp932 -t utf-8

4. Repository Operations

# リポジトリ一覧
az repos list --output table 2>&1 | iconv -f cp932 -t utf-8

# ブランチ一覧
az repos ref list --repository {REPO} --filter heads/ --output table 2>&1 | iconv -f cp932 -t utf-8

az devops invoke クイックリファレンス

重要: --resource には REST API URL のパスセグメント名ではなく、 CLI 内部に登録された resource 名（通常 camelCase）を指定すること。 誤った resource 名を指定すると --resource and --api-version combination is not correct という誤解を招くエラーが発生する（api-version ではなく resource 名が原因）。

# 基本構文
az devops invoke --area {area} --resource {resource} \
  --route-parameters {key=value ...} \
  --http-method {GET|POST|PATCH|DELETE} \
  --in-file {body.json} \
  --api-version "7.1" 2>&1 | iconv -f cp932 -t utf-8

# 利用可能な area/resource を確認（resource名が不明な場合は必ず実行）
az devops invoke --query "[?area=='{area}'].{Area:area, Resource:resourceName}" \
  --output table 2>&1 | iconv -f cp932 -t utf-8

よく使う resource 名マッピング

Output Format Tips

• --output table で人間が読みやすい表形式
• --output json でプログラム処理用
• --query で JMESPath フィルタリング（例: --query "[].{ID:id, Title:fields.\"System.Title\"}")

Error Handling