Azure SDKのCI/CDで NodeTool@0 の非推奨警告が出ている場合、まず確認すべき対応はシンプルです。Azure DevOps PipelineのYAMLで NodeTool@0 を UseNode@1 に置き換え、入力パラメーターを versionSpec から version に変更します。
今回の「Azure SDK documentation update: Replace deprecated NodeTool@0 with UseNode@1」は、Azure SDKそのもののAPI変更ではなく、Azure SDK for JavaScriptリポジトリのパイプライン基盤を更新する内容です。SDKパッケージへの直接影響はなく、主な対象はAzure DevOpsでNode.jsをセットアップしているCI/CD担当者、Azure SDK関連のリポジトリをfork・参照している開発チーム、同様のテンプレートを使っているプロジェクトです。(GitHub)
Azure SDKの今回の更新で変わったこと
今回の変更点は、Azure DevOpsのNode.jsセットアップ用タスクを更新するものです。Azure SDK for JavaScriptのPRでは、共有テンプレート eng/pipelines/templates/steps/use-node-version.yml に対して、NodeTool@0 を UseNode@1 へ、versionSpec を version へ変更しています。差分としては2行追加・2行削除の小さな変更ですが、パイプライン警告の解消と将来の保守性に関わる重要な更新です。(GitHub)
| 確認項目 | 変更前 | 変更後 | 実務上のポイント |
|---|---|---|---|
| Azure DevOpsタスク | NodeTool@0 | UseNode@1 | 非推奨タスクを使わない構成にする |
| Node.jsバージョン指定 | versionSpec | version | 入力名を変え忘れると移行ミスになりやすい |
| 対象範囲 | パイプライン基盤 | パイプライン基盤 | SDKのnpmパッケージやアプリコード変更ではない |
| 主な目的 | Node.jsの取得・PATH追加 | Node.jsの取得・PATH追加、プロキシサポート | 機能の置き換えだけでなく、公式タスクへの移行が目的 |
Microsoft Learnでも、NodeTool@0 は非推奨であり、代わりに UseNode@1 を使うよう案内されています。UseNode@1 は指定したNode.jsバージョンを検索・ダウンロード・キャッシュし、PATHに追加するタスクです。(Microsoft Learn)
なぜNodeTool@0からUseNode@1へ移行する必要があるのか
理由は、NodeTool@0 が非推奨となり、今後更新を受け取らないためです。Azure SDK for JavaScriptのIssueでは、パイプラインログに次のような警告が出ていたことが確認できます。
Task 'Node.js tool installer' version 0 (NodeTool@0) is deprecated.
This task is deprecated and will no longer receive updates.この警告自体は、すぐにビルドが失敗することを意味するものではありません。しかし、CI/CDの基盤で非推奨タスクを使い続けると、将来的なAzure DevOps側の仕様変更、ホステッドエージェント環境の更新、Node.jsバージョン取得処理の変化に追従しづらくなります。警告が出ている段階で置き換えておくのが安全です。(GitHub)
対応すべき人と、対応しなくてよい人
今回の更新は「Azure SDKを使っているすべての開発者」がすぐに作業すべき変更ではありません。影響は主にビルドパイプライン側にあります。
| 立場・環境 | 対応要否 | 確認内容 |
|---|---|---|
| Azure SDK for JavaScriptのCI/CDを運用しているチーム | 必要 | 共有テンプレートやYAMLで NodeTool@0 が残っていないか確認 |
| Azure DevOpsでNode.jsビルドを実行しているチーム | 必要 | 自社パイプラインに同じ非推奨警告が出ていないか確認 |
| Azure SDKリポジトリをforkして独自運用しているチーム | 必要 | fork側にも同等のテンプレート変更を反映 |
| npmでAzure SDKを利用しているだけのアプリ開発者 | 原則不要 | アプリコードやSDK利用方法への直接影響はない |
| GitHub Actionsだけを使っているチーム | 基本的に対象外 | Azure DevOps Pipelineのタスクを使っている場合のみ確認 |
Azure SDKのPR説明でも、影響範囲は「Pipeline infrastructure only」であり、SDKパッケージへの影響はないとされています。つまり、アプリケーションコードの修正やAzure SDKのバージョンアップが必要な更新ではありません。(GitHub)
移行時に最も重要なのはversionSpecからversionへの変更
単にタスク名を変えるだけでは不十分です。NodeTool@0 ではNode.jsバージョン指定に versionSpec を使っていましたが、UseNode@1 では version を使います。Azure SDK for JavaScriptのPRでも、この入力名の変更が明示的に行われています。(GitHub)
変更前の例です。
- task: NodeTool@0
inputs:
versionSpec: ${{ parameters.NodeVersion }}
displayName: "Use Node ${{ parameters.NodeVersion }}"変更後は次のようにします。
- task: UseNode@1
inputs:
version: ${{ parameters.NodeVersion }}
displayName: "Use Node ${{ parameters.NodeVersion }}"固定バージョンを直接指定している場合は、次のように書けます。
- task: UseNode@1
inputs:
version: '20.x'
displayName: 'Use Node.js 20'UseNode@1 の version は必須入力で、10.x、10.15.1、>=10.15.0 のようなSemVer形式のバージョン範囲を指定できます。既存の versionSpec の値をそのまま移せるケースは多いですが、入力名は必ず version に変える必要があります。(Microsoft Learn)
移行手順：まずYAML内のNodeTool@0を洗い出す
パイプラインが複数ある場合は、手作業でファイルを開くよりも検索した方が確実です。リポジトリ直下で次のように検索します。
grep -R "NodeTool@0\|versionSpec\|versionSource\|versionFilePath\|UseNodeV1" .Windows環境でPowerShellを使う場合は、次のように確認できます。
Get-ChildItem -Recurse -Include *.yml,*.yaml |
Select-String "NodeTool@0|versionSpec|versionSource|versionFilePath|UseNodeV1"確認したいポイントは次の4つです。
| 検索文字列 | 見つかった場合の判断 |
|---|---|
NodeTool@0 | UseNode@1 への置き換え候補 |
versionSpec | UseNode@1 では version に変更 |
versionSource / versionFilePath | .nvmrc などファイル読み取り利用の可能性があるため要注意 |
UseNodeV1 | 公式タスク名の UseNode@1 と混同していないか確認 |
特に UseNodeV1@1 には注意が必要です。Azure SDKのPRでは一度 UseNodeV1 への変更が検討されましたが、タスクが見つからずパイプラインが開始できない問題が発生し、最終的に公式Microsoftタスクである UseNode@1 が採用されています。(GitHub)
.nvmrcや独自ミラーを使っている場合はそのまま置き換えない
単純に versionSpec で 20.x のようなバージョンを指定しているだけなら、移行は比較的簡単です。一方で、NodeTool@0 の versionSource: fromFile や versionFilePath を使って .nvmrc からNode.jsバージョンを読んでいる場合は注意が必要です。
NodeTool@0 のドキュメントには versionSource、versionFilePath、nodejsMirror が入力として記載されています。一方、UseNode@1 のドキュメントに記載されている主な入力は version、checkLatest、force32bit、retryCountOnDownloadFails、delayBetweenRetries です。(Microsoft Learn)
.nvmrc を使い続けたい場合は、たとえば事前ステップでファイル内容を変数化してから UseNode@1 に渡す方法を検討します。
- bash: |
NODE_VERSION="$(sed 's/^v//' .nvmrc)"
echo "##vso[task.setvariable variable=NodeVersion]$NODE_VERSION"
displayName: "Read Node version from .nvmrc"
- task: UseNode@1
inputs:
version: '$(NodeVersion)'
displayName: "Use Node $(NodeVersion)"この方法を使う場合は、.nvmrc の中身が 20.11.1、20.x のように UseNode@1 の version が受け取れる形式になっているか確認してください。v20.11.1 のように先頭に v が付く運用では、上記のように取り除いてから渡すと安全です。
checkLatestは安易にtrueへ変更しない
UseNode@1 でも checkLatest を指定できますが、通常は false のままで問題ありません。Microsoft Learnでは、常に最新バージョンが必要な場合を除き false にすべきで、true にすると不要なダウンロードコストが発生する可能性があると説明されています。特にMicrosoft-hosted agentを使う環境では、ビルド時間が伸びる原因になります。(Microsoft Learn)
おすすめは、Node.jsのメジャーバージョンを明確に決めておく運用です。
- task: UseNode@1
inputs:
version: '20.x'
checkLatest: false「常に最新の20.xを使いたい」という意図があっても、本番向けCIでは急なマイナーバージョン更新がテスト結果に影響することがあります。安定性を優先するなら、20.11.1 のように具体的なバージョンを指定する方法も検討してください。
移行後に確認すべきチェックリスト
YAMLを書き換えたら、変更しただけで終わらせず、実際のパイプラインログで確認します。
| 確認項目 | 見るべきポイント |
|---|---|
| 非推奨警告 | NodeTool@0 is deprecated の警告が消えているか |
| タスク名 | ログ上で Use Node.js ecosystem / UseNode@1 が実行されているか |
| Node.jsバージョン | node -v の結果が意図したバージョンか |
| npmバージョン | npm -v が想定範囲内か |
| PATH | 後続の npm install、npm test、pnpm、yarn が動くか |
| self-hosted agent | 必要なエージェントバージョンやネットワーク接続に問題がないか |
確認用に、移行直後は次のようなステップを一時的に入れておくと原因切り分けがしやすくなります。
- script: |
node -v
npm -v
which node || where node
displayName: "Verify Node.js installation"UseNode@1 の要件として、Azure Pipelines Agentは 2.144.0 以上が必要とされています。self-hosted agentを使っている場合は、タスク置き換えとあわせてエージェントの更新状況も確認しておきましょう。(Microsoft Learn)
よくある移行ミスと対処法
| ミス | 起きる問題 | 対処法 |
|---|---|---|
versionSpec を残したままにする | 意図したNode.jsバージョン指定にならない可能性がある | UseNode@1 では version に変更する |
UseNodeV1@1 と書く | 組織にタスクがなくパイプラインが起動しない可能性がある | 公式タスク名の UseNode@1 を使う |
.nvmrc 読み取りをそのまま期待する | 旧タスクの versionFilePath 前提の構成が移行できない | 事前ステップでファイル内容を変数化する |
checkLatest: true にする | 毎回ダウンロードが増え、ビルド時間が伸びる可能性がある | 必要な場合だけtrueにする |
| Node.jsのメジャーバージョンを曖昧にする | 将来の環境差分でテスト結果が変わる | 20.x または具体的な固定バージョンを明示する |
今回のAzure SDKのPRでも、最終的な正解は「UseNode@1 を使い、入力は version にする」ことでした。警告文だけを見て UseNodeV1 に置き換えると、環境によってはタスクが見つからない問題にぶつかるため、公式ドキュメントのタスク名を基準にするのが安全です。(GitHub)
Azure SDK利用者が今すぐ取るべき行動
Azure SDKを使っているだけであれば、アプリケーションコードを急いで変更する必要はありません。ただし、Azure DevOpsでNode.jsを使うビルド、テスト、ドキュメント生成、SDKラッパーの生成などを行っている場合は、パイプラインの棚卸しを行うべきです。
まずはリポジトリ内で NodeTool@0 を検索し、見つかった箇所を UseNode@1 に置き換えます。次に、versionSpec を version に変更し、.nvmrc や独自ミラーを使っている特殊ケースがないか確認します。最後に、パイプラインを実行して、非推奨警告が消え、意図したNode.jsバージョンで後続タスクが動くことを確認してください。
今回の更新は小さなYAML変更に見えますが、CI/CDの警告を放置しないための良い機会です。Azure SDK関連のプロジェクトだけでなく、Azure DevOpsでNode.jsを使うすべてのリポジトリで、同じ観点の確認を進めておくと、将来のビルドトラブルを減らせます。
コメント