ado-axi

ado-axi

Azure DevOps REST API を利用する、エージェントが扱いやすい CLI です。複数の組織はプロファイルで管理され、各プロファイルには独自の組織、プロジェクト、認証情報（Azure CLI ログインまたは個人用アクセストークン）が含まれます。

通常の利用では npm install -g @jeffreyhaen/ado-axi でグローバルにインストールします。ado-axi が PATH にない場合は、コマンドの前に npx -y @jeffreyhaen/ado-axi を付けてください。

概要

まず、引数なしで ado-axi を実行してください。アクティブなプロファイルと、未完了の作業項目、プロジェクトでアクティブなプルリクエスト（active-pull-requests）、最近のパイプライン実行が表示されます。

ado-axi                      # dashboard
ado-axi config list          # configured profiles
ado-axi doctor               # authentication check per profile
ado-axi project list         # projects (30 most recently updated; --name <filter>, --limit N)

組織、プロジェクト、プロファイルの選択

すべてのコマンドで以下を指定でき、未知のフラグとして扱われることはありません。

• --profile <name> — 設定済みのプロファイル（ado-axi config list）。コマンドの前にも指定できます（ado-axi --profile acme pr list）。引数なしのダッシュボードでも使用できます。
• --org <org> / --project <project> — そのコマンド限りの上書きです。設定済みプロファイルに一致する --org は、そのプロファイルの認証情報を引き継ぎます。組織ルート URL（https://dev.azure.com/<org> または https://<org>.visualstudio.com）も使用できます。プロジェクト/API パスは不要です。
• $ADO_AXI_ORG / $ADO_AXI_PROJECT — 環境変数による上書きです。

貼り付けられた PR の Web URL から組織、プロジェクト、リポジトリ、ID を抽出し、それぞれを明示して渡してください。 タスクまたはプロジェクト固有のプロファイルから組織とプロジェクトを特定し、セッション中は同じ値を使用してください。プロジェクトのコンテキストが不明な場合は、ado-axi project list --org <org> を使ってください。対象のプロジェクトが依然として不明な場合はユーザーに確認してください。特に変更操作では、プロジェクトを任意に選択しないでください。

作業項目

ado-axi work-item list [--state open|all|<State>] [--type <type>] [--assigned-to @me|<name>]
                       [--iteration @current|<path>] [--area <path>] [--tag <tag>] [--search <text>]
                       [--query "<raw WIQL>"] [--limit 30]
ado-axi work-item get <id> [--comments] [--full]       # includes `rev` for compare-and-swap
ado-axi work-item create --type Task --title "..." [--description "..."] [--description-format markdown|html]
                         [--assigned-to <user>] [--parent <id>] [--area <path>] [--iteration <path>] [--tags "a; b"]
ado-axi work-item update <id> [--state <state>] [--title "..."] [--assigned-to <user>]
                              [--description "..."] [--description-format markdown|html]
                              [--add-tags a,b] [--remove-tags c] [--if-rev <n>]
                              [--set '{"Microsoft.VSTS.Common.Priority": 1}']
ado-axi work-item comment <id> [--body "..."] [--format markdown|html]
ado-axi work-item link list <id> [--limit 50]
ado-axi work-item link add <id> (--parent <id> | --child <id> | --related <id> | --pr <id>
                                 | --commit <40-hex> --repo <name> | --branch <name> --repo <name>)
                                [--comment "..."] [--if-rev <n>]

link list は階層リンクを作業項目 ID に、アーティファクトリンクをプルリクエスト ID、短縮コミット SHA、ブランチ名に解決します。link add は vstfs:// アーティファクト URI を自動で作成するため、URL ではなくプルリクエスト ID を渡してください。すでに存在するリンクは何もせずに処理します。

list は WIQL を自動で作成します。フラグで表現できない場合は --query を使ってください。 --description-format markdown は Markdown の説明文をレンダリングします。HTML を指定する場合に限り html を使ってください。この形式は説明文を指定した場合にのみ適用されます。 work-item comment は、コメントをデフォルトで Markdown として保存します。生の HTML を指定する場合に限り --format html を使ってください。この形式選択には、コメント API の 7.1-preview.4 以降が必要です。 update はべき等です。フィールドに現在と同じ値を設定すると、何も変更せずに処理を終了し、終了コード 0 を返します。

安全な同時更新

--if-rev <n> を指定すると、更新は比較交換になります。パッチには JSON-Patch の {"op":"test","path":"/rev"} が含まれるため、書き込みは指定したリビジョンに対してのみ適用され、それ以外の場合は PRECONDITION_FAILED で失敗します。二重の割り当てが黙って行われることはありません。work-item get から rev を読み取ってください。 --if-rev はべき等な変更なしのスキップも無効にするため、対象のフィールドは常に書き込まれます。

--add-tags / --remove-tags は、System.Tags 全体を置き換えるのではなく、タグのリストをその場で変更します（大文字と小文字を区別せず、重複を排除します）。そのため、無関係なタグは保持されます。文字列全体を置き換える --tags とは併用できません。

ado-axi work-item get 4211                  # read `rev` from the output
ado-axi work-item update 4211 --assigned-to [email protected] --add-tags agent-claimed --if-rev 7

プルリクエスト

ado-axi pr list [--repo <repo>] [--status active|draft|completed|abandoned|all] [--creator @me]
                [--reviewer @me] [--target <branch>] [--limit 30]
ado-axi pr get <id> [--threads] [--full]   # --full = complete description AND comment text
ado-axi pr comments <id> [--full]          # alias for `pr get <id> --threads`
ado-axi pr create --repo <repo> --source <branch> [--target main] --title "..." [--description "..."]
                  [--reviewers a,b] [--draft] [--work-items 1,2]
ado-axi pr update <id> [--title "..."] [--description "..."] [--draft true|false]
                       [--auto-complete true|false]
ado-axi pr complete <id> [--squash true|false] [--delete-source-branch true|false]
ado-axi pr abandon <id>
ado-axi pr checks <id> [--limit 10] [--full]
ado-axi pr diff <id> [--limit 20] [--full]
ado-axi pr reviewer list <id>
ado-axi pr reviewer add|remove <id> --reviewer <identity> [--required]
ado-axi pr approve <id> [--vote approve|approve-with-suggestions|wait-for-author|reject|reset]
ado-axi pr comment <id> [--body "..."] [--file <path> --line <n>] [--thread <id>]
ado-axi pr thread list <id> [--limit 20] [--full]
ado-axi pr thread reply <id> --thread <n> [--body "..."] [--resolve]
ado-axi pr thread resolve|reopen <id> --thread <n> [--status active|fixed|wont-fix|closed|by-design|pending]

レビューのフィードバック対応は pr thread で完了できます。list はスレッド ID と unresolved 件数を表示し、reply --resolve は一度の呼び出しで返信してスレッドを閉じます。また、resolve / reopen はすでに設定済みのステータスに対して、何もせずに処理したことを報告します。

安全なシェル入力

Markdown または複数行のコメント内容には、引用符で囲んだヒアドキュメントを標準入力にパイプして work-item comment、pr comment、pr thread reply を実行し、--body は省略します：

ado-axi pr thread reply 812 --thread 5 --resolve <<'EOF'
Fixed in `3f2a1c9`: `$value` is now validated.
EOF

バッククォート、$、!、または引用符を含むフラグ値を二重引用符で囲まないでください。Git Bash は ado-axi の起動前にこれらを展開するため、CLI には有効でも改変された入力が渡され、検出できません。 同じことは --title、--description、--set、--variables、--parameters、--query にも当てはまります： コマンドが対応している場合は標準入力を使うか、完全な JSON ペイロードを ado-axi api にパイプしてください。

pr list はレビュー状況（2/3 approved）を表示するため、状況を判断するための追加呼び出しは不要です。 --description を省略すると、作業項目と PR の説明をパイプで渡せます。pr update とレビュアーの 変更処理では、安全に検出された再試行は何も行わずに終了します。pr complete は現在のソースコミットを使用し、 ポリシーを回避せず、すでに完了している PR は何も行わずに終了します。pr abandon はすでに放棄された PR を 何も行わずに終了します。完了前に pr checks を実行すると、ポリシーと状態の概要を確認できます。上限付きの 対応可能項目リストでは不十分な場合に限り、--full を使ってください。

Git Bash のリポジトリパス

Windows では、Git Bash は引用符で囲んでも / で始まるリポジトリパスを変換します。インラインの コメントコマンドの前に MSYS_NO_PATHCONV=1 を付けて、--file が変更されずに Azure DevOps に渡るようにします。

例：

MSYS_NO_PATHCONV=1 ado-axi pr comment 812 --file '/src/Project/File.cs' --line 10 --body '...'

このプレフィックスを付けない場合、CLI は Git for Windows によって変換されたパスを元に戻します。スレッドを 作成する前に、その他の Windows パスと /bin または /usr/bin 配下のパスは拒否されます。

パイプライン

ado-axi pipeline list [--name <filter>]
ado-axi pipeline runs [--pipeline <id>] [--branch <branch>] [--result failed] [--limit 20]
ado-axi pipeline run --pipeline <id> [--branch <branch>] [--variables '{"k":"v"}']
ado-axi pipeline logs <run-id> [--log <log-id>] [--tail 120] [--full] [--failed-only]
ado-axi pipeline timeline <run-id> [--limit 20] [--full]
ado-axi pipeline watch <run-id> [--interval 10] [--timeout 1800]

watch は秒単位で指定し、2 秒未満の間隔を拒否します。また、認証、HTTP リクエスト、レスポンス本文を含めて 期限を適用します（デフォルトは 30 分です）。失敗、キャンセル、タイムアウト、予期しない結果の場合は、TOON 出力で ゼロ以外の終了コードを返します。

logs はデフォルトで最後のログの末尾を返します。特定のステップを指定するには --log <id> を渡してください。

実行が失敗した場合は、まず timeline を確認してください。失敗したステージ／ジョブ／ステップの名前、最初の エラー項目、読み取るログ ID が表示されます。logs --failed-only を使うと、そのステップのログに直接移動できます。

テスト

ado-axi test results <run-id> [--outcome failed|passed|aborted|not-executed|all] [--limit 20] [--full]
ado-axi test results --run <test-run-id>

<run-id> はパイプラインの実行 ID です。公開されたテスト実行のすべてのページが合計に反映されます。 結果数は --outcome と一致します。--limit は表示する結果数を制限しますが、合計は制限しません。 --full はエラーメッセージを展開しますが、この上限は増えません。ビルドが失敗した場合、通常は test results で「何が」壊れたか、pipeline logs --failed-only で「なぜ」壊れたかがわかります。

リポジトリ

ado-axi repo list [--name <filter>]
ado-axi repo branches --repo <name> [--name <filter>]
ado-axi repo file <path> --repo <name> [--ref <branch> | --commit <40-hex>] [--limit <lines>] [--full]
ado-axi ref list --repo <name> [--name <prefix>] [--limit 50] [--full]
ado-axi ref create --repo <name> --name <branch> (--source <branch> | --source-object-id <40-hex>)
ado-axi ref delete --repo <name> --name <branch> [--old-object-id <40-hex>]

repo file は、Azure DevOps から単一ファイルを直接読み取ります。デフォルトブランチ、ブランチ先端 （--ref）、または正確なリビジョン（--commit）を指定できます。作業コピーの外にあるファイル（別の リポジトリのファイルや、レビュー中のファイルのターゲットブランチ版）に使ってください。フォルダーとバイナリは 拒否されます。また、パスには pr comment --file と同じ /src/Project/File.cs 形式を使います。

参照の作成で既存のブランチが上書きされることはありません。削除時には正確なブランチを解決し、その現在のオブジェクト ID を Azure DevOps の同時実行ガードとして使用します。--old-object-id を指定すると、以前に確認したバージョンも検証されます。 意図したオブジェクトがすでに存在する場合、および対象がすでに存在しない場合、リクエストは何も行わずに終了します。

エスケープハッチ

専用コマンドがないもの（Wiki、テスト計画、コード検索、成果物、セキュリティ）は、未加工の REST ブリッジを 介して処理します：

ado-axi api _apis/wiki/wikis
ado-axi api _apis/testplan/plans --query 'filterActivePlans=true'
ado-axi api POST _apis/search/codesearchresults --host almsearch --body '{"searchText":"TODO"}'
cat payload.bin | ado-axi api POST _apis/wit/attachments --query 'fileName=payload.bin' --content-type application/octet-stream
ado-axi api _apis/projects --no-project           # organization-level path
ado-axi api 'https://vsrm.dev.azure.com/acme/Platform/_apis/release/releases?api-version=7.1'
ado-axi api PATCH _apis/wit/workitems/4211 --content-type json-patch \
  --body '[{"op":"test","path":"/rev","value":7},{"op":"add","path":"/fields/System.State","value":"Active"}]'

相対パスは https://dev.azure.com/<org>/<project>/ を使います。--host では dev（デフォルト）、vsrm、vssps、almsearch を選択できます。これら 4 つのホストの完全な HTTPS REST URL も 使用できます。この場合、URL の組織／プロジェクト／ホスト／クエリがデフォルトのコンテキストに置き換わり、 対応するプロファイル認証が使われます。競合するフラグや、別の組織の --profile は拒否されます。URL の コンテキストを上書きしないでください。クエリパラメーターを含む URL は引用符で囲んでください。--body が省略され、 標準入力がパイプされている場合、標準入力はリクエスト本文として変更されずに送信されます。--content-type には 省略形の json（デフォルト）、json-patch、merge-patch、text、または任意のメディアタイプを指定できます。 作業項目の書き込みには json-patch が必要です。

規約

• ADO の説明／コメントでは、#123 は作業項目、!123 は Azure DevOps の PR を参照します。GitHub の PR には、Boards／パイプラインが ADO で実行される場合でも、#123 や !123 だけではなく完全な URL を使用してください。
• 標準出力には TOON を出力します。エラーも TOON 形式で、次の手順を示す help リストを含みます。
• 終了コード：0 は成功（何も変更しない場合を含む）、1 は実行時エラー、2 は使用方法エラーです。
• 不明なフラグは名前を示して拒否されます。help の行を確認し、1 回だけ再試行してください。
• リストでは --limit と --fields a,b を指定できます。詳細表示は省略されるため、--full を指定してください。
• Windows／Git Bash では、.cmd シム経由で --description "$(cat file)" のような補間した CLI 引数として、大きな内容や複数行の内容を渡さないでください。cmd.exe によって切り詰められる場合があります。代わりにパイプで渡してください：cat file | ado-axi work-item update <id> または cat file | ado-axi api POST <path> --content-type <media-type>。
• 変更を加えるコマンド（create、update、complete、reviewer の追加／削除、ref の作成／削除、comment、approve、pipeline run）は実際の状態を変更します。ユーザーから依頼された場合にのみ実行してください。
• ポリシーを回避するために PR の完了機能を使わないでください。また、正確な対象が曖昧な ref は削除しないでください。