2026年5月21日扱いで確認したい「Microsoft Azure documentation update: Add Nerdbank.GitVersioning auto-versioning for bicep-deploy-common」は、Azureのリソース仕様変更ではなく、@azure/bicep-deploy-common のパッケージ公開時のバージョン付けを自動化する変更です。結論から言うと、開発者は今後 package.json の version を手作業で編集せず、version.json と Git のコミット履歴をもとに Nerdbank.GitVersioning がバージョンを計算する運用になります。元となる Azure/bicep-deploy の PR は 2026年5月20日に main へマージされています。(GitHub)
この変更で特に確認すべきなのは、CI/CD の checkout が浅いクローンになっていないか、公開ワークフローで npm run stamp-version と npm run reset-version が正しく動くか、そして依存側が 0.0.6 前提の固定バージョンや許可リストを持っていないかです。Bicep テンプレートそのものの書き方が変わる更新ではありませんが、パッケージ公開、リリース管理、ロックファイル、社内ミラー運用には影響が出る可能性があります。
Microsoft Azure documentation update: Add Nerdbank.GitVersioning auto-versioning for bicep-deploy-common の概要
今回の更新は、Azure/bicep-deploy リポジトリ内の packages/bicep-deploy-common に対して、Nerdbank.GitVersioning による自動バージョニングを追加するものです。Nerdbank.GitVersioning は、version.json と Git の履歴から SemVer 互換のバージョンを生成し、NPM パッケージなどにもバージョン情報をスタンプできるツールです。(GitHub)
@azure/bicep-deploy-common は、bicep-deploy の GitHub Action や Azure DevOps Task で使われる共通コードのパッケージです。PR上の package.json では、説明として「Common Code for bicep-deploy (GitHub Action/ADO Task)」と記載されています。(GitHub)
重要なのは、この更新が Azure の本番リソースや Bicep 構文を直接変更するものではない点です。影響の中心は、@azure/bicep-deploy-common をビルド・パック・公開するリリース工程にあります。
何が変わったのか
変更の中心は、package.json の固定バージョンを人が更新する方式から、Git 履歴に基づいて公開時にバージョンを計算する方式へ移行したことです。PRの説明では、version.json と nbgv-setversion を upload-package ワークフローに組み込み、@azure/bicep-deploy-common のパッチ番号を packages/bicep-deploy-common/ にスコープした commit height から計算するとされています。(GitHub)
| 項目 | 変更前 | 変更後 |
|---|---|---|
| バージョン管理 | package.json の version を手作業で更新 | version.json と Git 履歴から自動計算 |
package.json の version | 0.0.6 | 0.0.0-placeholder |
| パッチ番号 | 手作業または従来ワークフロー依存 | 対象パッケージ配下の commit height から算出 |
| CI/CD | 通常の checkout で足りる可能性があった | fetch-depth: 0 による完全な Git 履歴が必要 |
| 開発者の作業 | バージョン欄を直接編集する可能性あり | package.json の version は編集しない |
| minor / major 更新 | 手作業で package.json を更新 | version.json の version を更新 |
PRの最終差分では、packages/bicep-deploy-common/version.json が追加され、version は 0.1、pathFilters は "."、publicReleaseRefSpec は ^refs/heads/main$ になっています。(GitHub)
また、当初の説明では base 0.0 や versionHeightOffset 6 を使う案が示されていましたが、レビュー後のコミットで version.json は 0.1 に変更され、versionHeightOffset は外されています。PR上でも、既存公開済みパッケージとの衝突を避けるため 0.1.x から始める方向へのレビューコメントと、その後の修正が確認できます。(GitHub)
version.json の役割
今回追加された version.json は、Nerdbank.GitVersioning がどのようにバージョンを計算するかを決める設定ファイルです。最終的な内容は、概ね次の考え方です。
{
"$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
"version": "0.1",
"pathFilters": [
"."
],
"publicReleaseRefSpec": [
"^refs/heads/main$"
]
}version が 0.1 なので、公開されるパッケージは 0.1.<commitHeight> のような形で計算されます。Nerdbank.GitVersioning の FAQ では、git height は HEAD から、現在の major/minor を設定した起点までのコミット数として説明されています。(DotNet)
pathFilters が "." になっている点も重要です。この version.json は packages/bicep-deploy-common 配下に置かれているため、バージョンのパッチ番号はこのパッケージに関係する変更にスコープされます。PR内の VERSIONING.md でも、pathFilters: ["."] により、リポジトリ内の別の場所の変更ではこのパッケージのパッチ番号が増えないと説明されています。(GitHub)
publicReleaseRefSpec は、どの ref を「公開リリース」として扱うかを決める設定です。今回の設定では main ブランチだけがクリーンな X.Y.Z 形式の公開バージョンになり、それ以外のブランチでは Git SHA を含むサフィックス付きのバージョンになる想定です。(GitHub)
package.json を手で編集しない運用に変わる
開発者にとって最も分かりやすい変更は、packages/bicep-deploy-common/package.json の version が 0.0.6 から 0.0.0-placeholder に変わったことです。あわせて、stamp-version と reset-version の npm script が追加されています。(GitHub)
"scripts": {
"typecheck": "tsc --noEmit",
"build": "npm run typecheck && tsdown --config ./tsdown.config.mts",
"stamp-version": "nbgv-setversion",
"reset-version": "nbgv-setversion --reset"
}通常の開発では、package.json の version を見て「現在の公開予定バージョン」を判断しないようにする必要があります。リポジトリ上の値はプレースホルダーであり、実際の公開バージョンはワークフロー実行時に nbgv-setversion によって一時的に書き込まれます。
この設計には、古い固定バージョンを誤って公開するリスクを減らす狙いがあります。PRで追加された VERSIONING.md では、package.json の version は意図的に sentinel value として 0.0.0-placeholder に設定され、公開ワークフローで上書きされ、パッケージング後に戻されると説明されています。(GitHub)
upload-package ワークフローで変わる処理
.github/workflows/upload-package.yml では、Nerdbank.GitVersioning が commit height を計算できるように、checkout に fetch-depth: 0 が追加されました。GitHub Actions の浅いクローンでは十分な履歴が取得できず、Git 履歴に基づくバージョン計算が正しく動かない可能性があるためです。(GitHub)
ワークフローの流れは、次のように変わります。
| 順序 | 処理 | 確認ポイント |
|---|---|---|
| 1 | リポジトリを checkout | fetch-depth: 0 で完全な履歴を取得する |
| 2 | npm ci を実行 | nerdbank-gitversioning が devDependency として入る |
| 3 | npm run stamp-version | package.json に実際の公開バージョンを一時反映 |
| 4 | build / pack | npm pack の出力から filename と version を取得 |
| 5 | npm run reset-version | package.json を 0.0.0-placeholder に戻す |
| 6 | パッケージをアップロード | 生成された tarball のバージョンを使う |
PRでは、Stamp version (Nerdbank.GitVersioning) ステップとして npm run stamp-version が追加され、パッケージング後には Reset version ステップで npm run reset-version が always() 条件付きで実行されるようになっています。(GitHub)
この always() は実務上かなり重要です。途中で build や pack が失敗しても、作業ツリーにスタンプ済みのバージョンが残りにくくなります。ローカル検証や self-hosted runner で作業ディレクトリを再利用する場合は、特に差分の残留に注意が必要です。
管理者が確認すべき影響範囲
Azure 管理者や DevOps 管理者は、Azure のデプロイ設定そのものよりも、CI/CD と依存管理の確認を優先すべきです。
| 確認対象 | 見るべきポイント | 放置した場合のリスク |
|---|---|---|
| GitHub Actions / Azure DevOps Pipeline | 完全な Git 履歴を取得できるか | commit height が計算できず、バージョン生成が失敗する |
| パッケージ許可リスト | 0.0.6 固定になっていないか | 0.1.x 系の取り込みがブロックされる |
| lockfile / 社内ミラー | 新しいバージョンを取得できるか | ビルド環境だけ古いパッケージを使い続ける |
| release note / 監査ログ | 実際の公開バージョンをどこから取得するか | package.json の placeholder を誤って記録する |
| ブランチ運用 | main 以外から公開していないか | サフィックス付きバージョンになる、または期待と異なる公開形式になる |
特に、社内で GitHub リポジトリをミラーしている場合や、CIで sparse checkout、shallow clone、手動 tarball 生成を行っている場合は注意が必要です。Nerdbank.GitVersioning は Git 履歴を前提にバージョンを計算するため、ソースコードだけをコピーした環境では同じ結果にならない可能性があります。
開発者がやるべき確認
開発者は、まず「どのファイルを触るべきか」を整理すると失敗を減らせます。
| やりたいこと | 触るファイル・コマンド | 注意点 |
|---|---|---|
| 通常の修正を入れる | ソースコードを変更するだけ | patch 番号は自動で進む |
| patch を手動で上げたい | 原則不要 | package.json の version は編集しない |
| minor を上げたい | version.json の version を 0.2 などに変更 | patch height は新しい minor で再計算される |
| major を上げたい | version.json の version を 1.0 などに変更 | 破壊的変更の扱いとリリースノートを合わせる |
| ローカルで確認したい | npx nbgv get-version | packages/bicep-deploy-common 配下で実行する |
| tarball を検証したい | stamp-version → build → pack → reset-version | reset を忘れると作業ツリーに差分が残る |
PRで追加された VERSIONING.md では、ローカル確認用に npx nbgv get-version を実行し、NpmPackageVersion を確認する方法が案内されています。また、手元で npm run stamp-version、npm run build、npm pack、npm run reset-version を順に実行する検証手順も示されています。(GitHub)
実務では、レビュー時に package.json の version 変更が含まれていたら、まず不要な手作業変更ではないか確認しましょう。今回の変更後は、version の直接編集は「親切な修正」ではなく、リリースワークフローを壊す可能性がある変更になります。
移行時に起きやすい失敗
package.json の placeholder を実バージョンだと誤解する
最も起きやすいのは、0.0.0-placeholder を見て「パッケージが 0.0.0 に戻った」と判断してしまうことです。これは公開用の実バージョンではありません。実際のバージョンは、公開ワークフロー内で nbgv-setversion が書き込んだ値を npm pack が読み取ります。
CIログ、生成された .tgz、npm pack の JSON 出力、または npx nbgv get-version の NpmPackageVersion を確認してください。
shallow clone のままにしている
GitHub Actions の actions/checkout は、設定によっては履歴が浅い状態になります。今回のワークフローでは fetch-depth: 0 が明示されましたが、社内で同等の処理を別パイプラインに移植している場合は、同じ設定を忘れやすいです。(GitHub)
特に Azure DevOps Pipeline に置き換えている場合は、checkout の fetch depth 設定を確認してください。履歴が不足すると、commit height の計算結果が期待とズレたり、バージョン計算に失敗したりする可能性があります。
main 以外から公開している
publicReleaseRefSpec は ^refs/heads/main$ のみです。つまり、クリーンな公開バージョンを作る前提は main ブランチです。リリースブランチやタグから公開する運用に変える場合は、version.json の publicReleaseRefSpec も設計し直す必要があります。
この設定を見落とすと、意図せず -g<sha> のようなサフィックス付きバージョンになり、パッケージ利用側のバージョン制約や社内ポリシーに引っかかる可能性があります。
パッケージ外の変更で patch が進むと思い込む
pathFilters によって、バージョン計算は packages/bicep-deploy-common にスコープされています。リポジトリの別ディレクトリだけを変更しても、このパッケージの patch 番号は進まない設計です。PR内の説明でも、pathFilters により他の場所の変更ではこのパッケージの patch 番号が増えないとされています。(GitHub)
これはモノレポでは合理的ですが、「リポジトリにコミットが増えたら必ず全パッケージのバージョンも上がる」と考えているチームでは認識のズレが出ます。リリースノートや監査手順では、「どのパスの変更がどのパッケージのバージョンに反映されるか」を明確にしておくべきです。
依存している側は何を見ればよいか
@azure/bicep-deploy-common を直接または間接的に利用している場合は、まず依存関係の指定を確認してください。
固定バージョンで 0.0.6 を参照している場合、新しい 0.1.x 系は自動では入りません。^0.0.6 のような指定でも、SemVer 上は 0.1.x へ広がらないケースがあります。利用側で更新を取り込むには、依存バージョンの明示的な変更や lockfile の更新が必要になる可能性があります。
一方で、この変更はパッケージのバージョニング方法に関するものです。PR上で確認できる主な変更は、ワークフロー、version.json、package.json、VERSIONING/CONTRIBUTING の更新であり、Azure リソースのデプロイ挙動そのものを変える内容としては示されていません。(GitHub)
そのため、確認の優先順位は次の順で考えると実務的です。
| 優先度 | 確認内容 | 判断基準 |
|---|---|---|
| 高 | ビルドや公開が失敗しないか | CIで nbgv-setversion と npm pack が成功する |
| 高 | 依存バージョンを取得できるか | lockfile、社内レジストリ、許可リストが 0.1.x を許容する |
| 中 | リリース監査に残す値 | package.json ではなく、生成された package version を記録する |
| 中 | main 以外の公開運用 | publicReleaseRefSpec と実際のリリースブランチが一致する |
| 低 | Bicep テンプレート修正 | 今回の変更だけなら通常は不要 |
展開前のチェックリスト
本番に近いリリース工程で使っている場合は、次の順で確認すると安全です。
packages/bicep-deploy-common/package.jsonのversionを手で戻そうとしていないか確認する- CIの checkout が完全な履歴を取得しているか確認する
npm ci後にnerdbank-gitversioningが使えるか確認するnpm run stamp-version後のpackage.jsonに期待するバージョンが入るか確認するnpm packの出力バージョンと tarball 名を確認するnpm run reset-version後に0.0.0-placeholderに戻るか確認する- 依存側の lockfile、社内ミラー、パッケージ許可リストを更新する
- リリースノートでは
0.0.0-placeholderではなく、実際の公開バージョンを記録する
ローカルで確認する場合は、次のような流れが分かりやすいです。
cd packages/bicep-deploy-common
npx nbgv get-version
npm run stamp-version
npm run build
npm pack
npm run reset-versionreset-version 後に差分が残る場合は、生成物や lockfile、ビルド成果物が意図せず変更されていないか確認してください。
今回の変更をどう評価すべきか
この更新の価値は、単に「バージョン番号を自動で増やす」ことではありません。リリース工程で本当に重要なのは、どのコミットからどのパッケージが作られたかを追跡しやすくすることです。
手作業のバージョン更新では、次のような問題が起きがちです。
- 修正は入ったが
package.jsonのversionを上げ忘れる - 逆に、バージョンだけ上げて実体の変更が分かりにくくなる
- 複数人の PR で version 更新が衝突する
- 公開済みバージョンとの重複に気づくのが遅れる
- リリース後に、どのコミット由来のパッケージか追跡しにくい
Nerdbank.GitVersioning は、Git 履歴をもとに一意なバージョンを生成し、タグやブランチ名に依存しすぎない再現性を重視する設計です。公式リポジトリでも、各コミットに一意で SemVer に適合するバージョンを生成できることや、タグへの依存を避けられることが特徴として説明されています。(GitHub)
ただし、自動化されるからこそ、運用ルールは明確にする必要があります。package.json の version を見て判断しない、浅い clone でビルドしない、minor/major は version.json で管理する、という基本をチーム内で共有しておくことが重要です。
まず対応すべきこと
今回の Microsoft Azure documentation update: Add Nerdbank.GitVersioning auto-versioning for bicep-deploy-common は、Azure 利用者全員が即座に設定変更すべき更新ではありません。優先して対応すべきなのは、@azure/bicep-deploy-common のビルド、公開、依存管理に関わる管理者と開発者です。
まずは、自分たちの環境で package.json の version を参照している処理がないかを確認してください。次に、CI/CD が完全な Git 履歴を取得できるか、npm run stamp-version と npm run reset-version が期待通り動くかを検証します。最後に、依存側の lockfile や社内レジストリのルールが 0.1.x 系のバージョンを受け入れられるかを確認すれば、移行時のトラブルをかなり減らせます。
この変更は、Bicep デプロイそのものを難しくするものではなく、リリースの再現性と追跡性を高めるための更新です。運用側では「バージョンは手で書くもの」から「ワークフローが計算して記録するもの」へ発想を切り替えることが、最も重要な対応になります。
コメント