Azure DevOps Operations Skill

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

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

コマンド体系

| レイヤー | コマンド | 用途 | |---------|---------|------| | Work Items | az boards work-item / az boards query | CRUD, WIQL クエリ | | Pull Requests | az repos pr | 作成, レビュー, 投票, マージ | | Repositories | az repos / az repos ref | リポジトリ管理, ブランチ管理 | | Pipelines | az pipelines / az pipelines build | 実行, 監視, 変数管理 | | REST API 補完 | az devops invoke | 上記で対応できない操作全般 |

`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 名マッピング

| 目的 | area | resource (正しい名前) | |------|------|----------------------| | PR スレッド取得・追加 | git | pullRequestThreads | | PR スレッド内コメント | git | pullRequestThreadComments | | PR イテレーション | git | pullRequestIterations | | PR イテレーション変更 | git | pullRequestIterationChanges | | コミット間差分 | git | commitDiffs | | ビルドタイムライン | build | Timeline | | ビルドログ | build | logs |

Output Format Tips

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

Error Handling

| エラー | 対処 | |--------|------| | az devops: command not found | az extension add --name azure-devops | | TF401019: unauthorized | az devops login で PAT を再設定 | | TF200016: project not found | --project パラメータ確認、az devops configure --defaults project=XXX | | az devops invoke で area 不明 | az devops invoke --query "[].{Area:area}" で確認 | | --resource and --api-version combination is not correct | resource 名が間違っている（api-version の問題ではない）。上記マッピング表を参照するか az devops invoke --query "[?area=='{area}'].resourceName" で確認 | | 日本語が文字化け | 2>&1 \| iconv -f cp932 -t utf-8 をパイプ末尾に付与 |

Agent Skills: Azure DevOps Operations

Install this agent skill to your local

Skill Files