Azure Boards を接続する: 手順ガイド
失敗したテストごとに作業項目を1件作成し、そのテストが再び失敗するとコメントを追加し、問題なく成功すると完了状態にします。同じトークンでテスト結果の公開やパイプラインの実行待ちへの追加も行います。このガイドでは、準備から接続確認までの手順と、発生しうるエラーの原因および解決方法を説明します。
最終更新日:
認証情報は非公開にしてください。 トークン、キー、パスワード、Webhook URL をチャットに貼り付けないでください。入力先は Studio → 設定 → 連携のみにしてください。認証情報はワークスペースの .env ファイルに保存され、画面上では点で表示されます。AI アシスタントにも同じことが当てはまります。このガイドに沿って手順を案内することはできますが、トークンを伝える必要はありません。
必要なもの
- Azure DevOps Services の組織: https://dev.azure.com/<organization> または https://<organization>.visualstudio.com (自社のマシンで稼働する Azure DevOps Server には対応していません)。
- 作業項目の登録先となるプロジェクトの名前。
- 作業項目 → 読み取り & 書き込みの権限を持つ個人用アクセス トークン (PAT)。CI で実行も使用する場合は、ビルド → 読み取り & 実行の権限も必要です。
- プロジェクトのプロセスを把握しておくこと。プロセスによって作業項目の種類が決まります: Basic には Issue、Epic、Task があり (Bug はありません)、Agile、Scrum、CMMI には Bug があります。
認証情報を取得する
- dev.azure.com を開き、ユーザー設定 → 個人用アクセス トークン → 新しいトークンに進みます。
- 組織を選択し、有効期限を設定して、スコープでカスタム定義を選びます。
- 作業項目 → 読み取り & 書き込みにチェックを入れ (CI で実行を使用する場合はビルド → 読み取り & 実行も追加)、トークンを作成してその場でコピーします。表示されるのは一度だけです。
- クリップボードに保持してください。Studio (次の手順) 以外には貼り付けないでください。
Studio で接続する
- Studio で、設定 → 連携 → Azure DevOps に接続を開きます。
- Azure DevOps のリンク (ボード、作業項目、プロジェクトページのいずれか) を貼り付け、接続を確認を押します。Studio に組織とプロジェクトが保存されます。
- 入力を求められたら PAT を入力し、保存 & 確認を押します。"作業項目の登録先"でプロジェクトを選択します。
- 接続確認で、プロジェクトに Bug という作業項目の種類がないと表示された場合は、
AZURE_BOARDS_WORK_ITEM_TYPEを表示された種類のいずれか (Basic プロジェクトでは Issue) に設定し、AZURE_BOARDS_DONE_STATEをそのプロセスに存在する状態 (Basic: Done) に設定します。 AZURE_BOARDS_ENABLEDを有効にします。
動作を確認する
- 接続を確認すると、"トークンで N 件のプロジェクトを参照できます"および"<project> には <type> の作業項目を登録できます"と表示されます。この確認は読み取りのみで、作業項目は作成しません。
- 設定 → 連携 → チケットを開き、テスト用チケットを作成を押します。nexus-test タグとスクリーンショットの添付がある作業項目が1件作成されます。
- Azure Boards でその作業項目を開き、タグと添付ファイルを確認し、確認が済んだら削除します。
よくあるエラー
| 確認できる結果 | 原因 | 解決方法 |
|---|---|---|
| "Azure DevOps がトークンを拒否しました" (HTTP 203 または 401) | PAT が間違っている、有効期限が切れている、取り消されている、コピーが不完全、または別の組織で作成されています。 | AZURE_DEVOPS_ORG_URL と同じ組織で、作業項目 → 読み取り & 書き込みの権限を持つ新しい PAT を作成し、再度保存します。 |
| HTTP 403 | PAT は有効ですが必要なスコープがないか、ユーザーにそのプロジェクトの権限がありません。 | PAT のスコープを編集するか (作業項目 → 読み取り & 書き込み; CI で実行を使用する場合はビルド → 読み取り & 実行)、プロジェクト管理者にアクセス権を依頼します。 |
| HTTP 404 | 組織またはプロジェクト名が存在しないか、プロジェクト名が変更されています。 | 正しいプロジェクトのリンクを貼り付け、一覧からそのプロジェクトを選択します。 |
| VS402323 "作業項目の種類 Bug が存在しません" | プロジェクトのプロセスに、その名前の作業項目の種類がありません。Basic プロジェクトには Issue、Epic、Task があり、Bug はありません。 | AZURE_BOARDS_WORK_ITEM_TYPE を接続確認で表示された種類 (Basic: Issue) に、AZURE_BOARDS_DONE_STATE をその状態のいずれか (Basic: Done) に設定して、再度接続を確認します。 |
| "<project> には … という名前の作業項目の種類がありません" | VS402323 と同じ原因ですが、項目が登録される前に「接続を確認」で検出されます。 | AZURE_BOARDS_WORK_ITEM_TYPE をそのメッセージに表示された種類のいずれかに設定するか、別のプロジェクトを選択してください。 |
| "これは Azure DevOps のリンクではありません" | アドレスが dev.azure.com/<organization> または <organization>.visualstudio.com のものではないか、http:// で始まっています。 | Azure DevOps Services のアドレスバーからアドレスをコピーしてください。Azure DevOps Server はサポートされていません。 |
| "Azure DevOps に接続できませんでした (…)" または "20 秒以内に応答がありませんでした" | VPN やプロキシ、またはネットワーク未接続のため、この PC から Azure DevOps に接続できません。 | 同じ PC のブラウザーで dev.azure.com を開き、もう一度確認してください。 |
| テストに合格しても完了状態にならない | その種類ではプロセスが AZURE_BOARDS_DONE_STATE を受け付けないため、項目にはコメントのみが追加されます。 | AZURE_BOARDS_DONE_STATE をその種類の状態に設定してください (Basic: Done; Agile のバグ: Resolved)。 |
| 確認はすべて成功するのに作業項目が表示されない | AZURE_BOARDS_ENABLED が false になっているか、判定が FLAKY または環境に関する判定であるか、サンドボックスでの実行であるか、そのテストに未完了の作業項目がすでにあります (再度失敗した場合は、代わりにコメントが追加されます)。 | AZURE_BOARDS_ENABLED を有効にして、「テスト用チケットを作成」で接続を確かめてください。 |
設定キー
| キー | 主な機能 | 有効な値 | 確認方法 |
|---|---|---|---|
AZURE_BOARDS_ENABLED | 失敗時に Azure 作業項目を作成 | true または false | 「接続を確認」が成功してから有効にし、「テスト用チケットを作成」を実行してください。 |
AZURE_DEVOPS_ORG_URL | Azure DevOps 組織のアドレス | https://dev.azure.com/<organization> または https://<organization>.visualstudio.com | 「接続を確認」で組織が表示されます。リンクを貼り付けると自動入力されます。 |
AZURE_DEVOPS_PROJECT | Azure DevOps のプロジェクト名 | Azure DevOps に表示されているとおりの正確なプロジェクト名 | 「接続を確認」で、トークンから参照できるプロジェクトが一覧表示されます。 |
AZURE_DEVOPS_PAT | Azure DevOps のアクセストークン (機密情報、このコンピューターにのみ保存) | 1 行で入力、引用符や空白なし | 「接続を確認」で "トークンが拒否されました" と表示される場合、トークンが誤っているか、有効期限切れか、別の組織のものです。 |
AZURE_BOARDS_WORK_ITEM_TYPE | 失敗時の Azure チケットの種類 | プロジェクトのプロセスにある種類: Bug (Agile, Scrum, CMMI) または Issue (Basic) | 「接続を確認」で "<project> は <type> の作業項目を受け付けます" と表示されるか、そのプロジェクトの種類が一覧表示されます。 |
AZURE_BOARDS_DONE_STATE | テスト合格時の Azure の状態 | その作業項目の種類にある状態: Resolved (Agile のバグ), Done (Basic の課題) | 問題なく合格すると項目の状態が変わります。プロセスがその状態を拒否した場合は、コメントのみが追加されます。 |
AZURE_PIPELINE_ID | CI で実行する Azure パイプライン | Azure パイプラインの数値 ID (「CI で実行」専用) | nexus ci-remote --provider=azure はそのパイプラインを実行待ちに追加します。Build → Read & execute が必要です。 |
詳細: すべての連携, 設定ガイド, 問題の解決方法. その他のガイド: Jira Cloud, Slack, Microsoft Teams, Telegram, GitHub Issues.
まだ解決しませんか? Studioに表示されるエラー行をそのまま添えて、[email protected]までご連絡ください。トークンは記載しないでください。