netbox-branching

NetBox のブランチ

ブランチ機能により、NetBox で Git のような変更の分離ができます。各ブランチは分離された PostgreSQL スキーマを使用します。特別なヘッダーを使ってそのスキーマに対する読み取りと書き込みを行い、変更をメインにマージします。

**NetBox のブランチ機能に関する知識は古くなっている可能性があります。**ブランチの状態、マージ戦略、API の動作は、プラグインのリリースごとに変わります。事前学習済みの知識より、情報の取得を優先してください。

情報取得元

情報源	URL／方法	用途
Branching のドキュメント	https://netboxlabs.com/docs/extensions/branching/	全般的なリファレンス、ライフサイクル、設定
Branching REST API	https://netboxlabs.com/docs/extensions/branching/rest-api/	エンドポイントの詳細
Branching リポジトリ	https://github.com/netboxlabs/netbox-branching	ソース、変更履歴、イシュー
NetBox MCP サーバー	設定されている場合 — ブランチの状態を確認し、ブランチを一覧表示	最新のブランチ状態
NetBox Platform MCP	設定されている場合 — ブランチのライフサイクル全般を操作	作成、同期、マージの確認

最初に行うこと：接続を確認する

Branching プラグインがインストールされていて、トークンにアクセス権があることを確認します。

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/plugins/branching/branches/" | python -m json.tool

ページ分割されたブランチの一覧（または空の結果）が表示されます。404 が返された場合、Branching プラグインはインストールされていません。403 が返された場合、トークンに netbox_branching の権限がありません。

---

プラグイン： netbox_branching — NetBox のバージョンに応じて選択する、サポート対象の 2 つの系列があります。

NetBox	プラグイン系列	最新
4.7.x	1.2.x（min_version 4.7.0。4.6 以下では読み込まれません）	1.2.2（2026-10-08）
4.4.1–4.6.x	1.1.x（4.7 では読み込まれません）	1.1.3（2026-08-26）

1.0.x／0.9.x は後継バージョンに置き換えられています。NetBox 4.7 へ移行する前に 1.1.x へアップグレードし、その後 NetBox のアップグレードに合わせて 1.2.x へアップグレードしてください。このスキルが対象とする範囲は NetBox 4.5～4.7 です。

**1.2.0 は NetBox 4.7 への移植版です。**NetBox 4.7 では django-mptt が PostgreSQL の ltree に置き換えられ、パスや非正規化フィールドの保守が DB トリガーに移されました。1.2.0 ではそれらのトリガーがすべてのブランチスキーマに複製されるため、ブランチ内でも階層構造（リージョン、ロケーション、テナントグループ、モジュールベイなど）が同じように動作します。エンドポイント、権限コード名、squash 戦略、11 状態のライフサイクルはどちらの系列でも同じです。1.2 系列のみの API は recover/（1.2.1）だけです。バージョンに関する注意を参照してください。

主な概念

• **ブランチ = 分離されたスキーマ。**プロビジョニング時に作成され、アーカイブまたは削除時に破棄されます。各ブランチは独自のデータベーステーブルを持ちます。
• schema_id（8 文字の英数字）は、API アクセスに使用するブランチ識別子です。名前でも数値 ID でもありません。
• 負荷の高い操作はすべて非同期です — プロビジョニング、同期、マージ、リバートは Job を返します。完了するまで状態を確認してください。
• 競合は、メインとブランチが同じオブジェクトのフィールドを変更した場合に発生します。マージや同期を進める前に、競合を確認する必要があります。

ブランチのライフサイクル

11 個の状態があります。完全な状態遷移図については、references/branch-lifecycle.md を参照してください。

状態	意味
new	作成済みですが、まだプロビジョニングされていません
provisioning	スキーマをコピー中です（非同期）
ready	使用可能です — 読み取り／書き込みが許可されています
syncing	main からブランチへ反映中です（非同期）
migrating	DB マイグレーションを適用中です（非同期）
merging	ブランチから main へ反映中です（非同期）
reverting	マージを取り消し中です（非同期）
merged	マージに成功しました。読み取り専用です
archived	スキーマは削除され、メタデータは保持されています
pending-migrations	NetBox のアップグレード後にマイグレーションが必要です
failed	プロビジョニングまたはマイグレーションに失敗しました。終端状態です — 削除して再作成してください

遷移状態（provisioning、syncing、migrating、merging、reverting）は中断できません。捕捉されたエラーが発生すると、以前の安定状態に戻ります（syncing／merging → ready、reverting → merged）。ただし、provisioning と migrating は failed になります。

ワーカーが強制終了された場合（OOM、kill -9、Pod の退避）： エラー処理が実行されないため、ブランチは遷移状態のままになり、その操作は無効になります。（1.2.1+／NetBox 4.7）1 時間ごとのジョブ（auto_recover_stuck_branches、デフォルトは True）でリセットするか、必要に応じて POST /api/plugins/branching/branches/<id>/recover/ を実行します（change_branch が必要です。ジョブがまだ実行中に見える場合は {"force": true}、中断された同期／マイグレーションを再実行する場合は {"retry": true} を指定します）。リセット先：provisioning→failed、syncing／merging→ready、migrating→pending-migrations、reverting→merged。1.1.x には復旧エンドポイントがありません。

クイックリファレンス — よく使うワークフロー

作成して準備完了まで待つ

POST /api/plugins/branching/branches/
Content-Type: application/json
Authorization: Bearer <token>

{"name": "add-new-site", "description": "Adding London site"}

レスポンスには schema_id が含まれます。自動的にプロビジョニングされます。準備ができるまでポーリングします。

GET /api/plugins/branching/branches/<id>/

status フィールドを確認し、ready になるまで待ちます。通常、DB のサイズに応じて数秒から数分かかります。

ブランチコンテキストを有効にする

ブランチコンテキストでのすべての API／GraphQL リクエストには、次のヘッダーを追加してください。

X-NetBox-Branch: <schema_id>

値にはブランチ名や ID ではなく、schema_id（例：a1b2c3d4）を指定します。

その他の方法（UI のみ。API 自動化には使用しないでください）：

• Cookie：active_branch=<schema_id>
• クエリパラメーター：?_branch=<schema_id>

ブランチは ready 状態でなければならず、そうでない場合リクエストは拒否されます — （1.2.2+）400 Selected branch is not ready.（1.2.2 より前は 500）。レスポンスにはブランチ名も状態も意図的に含まれません（REST 認証より前に返されるため）。そのため、ブランチの status をポーリングして ready になるまで待ってください。

ブランチで変更を加える

ブランチヘッダーを付けて、通常の NetBox API エンドポイントを使用します。

POST /api/dcim/sites/
X-NetBox-Branch: a1b2c3d4
Content-Type: application/json

{"name": "London", "slug": "london", "status": "planned"}

変更はブランチのスキーマ内に分離されます。main には影響しません。

変更を確認する（ChangeDiffs）

GET /api/plugins/branching/changes/?branch_id=<id>

変更内容を示す ChangeDiff レコードが返されます — オブジェクトの種類、操作（作成／更新／削除）、変更前と変更後のデータが含まれます。

main から同期する

main の最新の変更をブランチに反映します。

POST /api/plugins/branching/branches/<id>/sync/
Content-Type: application/json

{"commit": true}

Job オブジェクトが返されます。完了するまでジョブ URL をポーリングしてください。main で親が削除されている場合、同期によってブランチにのみ存在する子オブジェクトが連鎖的に削除されることがあります。

ドライラン： {"commit": false} — 適用せずに検証します。

メインへのマージ

POST /api/plugins/branching/branches/<id>/merge/
Content-Type: application/json

{"commit": true}

Job を返します。成功すると、ブランチのステータスは merged（読み取り専用）になります。

マージ戦略：

• Iterative（デフォルト）— ブランチの各 ObjectChange を時系列順にメインへ再適用し、変更ごとのユーザーと時刻の帰属情報を保持します。失敗しない限り、この方法を使用してください。
• Squash — オブジェクトごとの最終的な操作にまとめ、外部キー依存関係の順序で適用します（1.1.1 以降は長さを問わない外部キー循環に対応）。CREATE+DELETE はスキップされます。メインの変更履歴に記録されるのはマージしたユーザーです。重複オブジェクトや中間状態が原因の失敗から復旧する場合に使用してください。

REST に戦略パラメーターはありません。 merge/ が受け付けるのは commit と acknowledge_conflicts のみです。API によるマージは iterative で実行されます。Squash を選択できるのは UI のマージフォームのみです（merge_strategy は REST シリアライザーに含まれません）。マージバリデーター（Changes プラグインの承認済み CR ゲートなど）はエンドポイントではなく ジョブ によって確認されます。リクエストは 200 + Job を返し、その後ジョブが Merging this branch is not permitted. というエラーになります。ドライラン（commit: false）ではバリデーターはスキップされます。

競合の処理

ChangeDiffs に競合するフィールドがある場合、同期／マージは競合の詳細とともに 409 を返します。

{
  "detail": "All conflicts must be acknowledged before this action can proceed.",
  "conflicts": [{"id": 6, "object_type": "dcim.device", "object_id": 42, "object_repr": "switch-01",
    "action": {"value": "update", "label": "Updated"},
    "conflicts": ["name", "status"],
    "conflicting_data": {
      "original": {"name": "old"}, "branch": {"name": "branch-val"}, "main": {"name": "main-val"}
    }}]
}

続行するには、"acknowledge_conflicts": true を指定して再送信してください。競合を確認した場合は、ブランチの値が優先されます。

詳細については、references/conflict-resolution.md を参照してください。

マージ済みブランチの取り消し

POST /api/plugins/branching/branches/<id>/revert/
Content-Type: application/json

{"commit": true}

merged 状態のブランチでのみ機能します。ブランチを ready 状態に戻します。非同期ジョブです。

アーカイブ

POST /api/plugins/branching/branches/<id>/archive/

merged 状態のブランチのみが対象です（それ以外の場合は 400）。同期処理で、更新されたブランチを返し、ジョブはありません。スキーマを削除し、メタデータとイベント履歴を保持します。アーカイブしたブランチは取り消せなくなります。終端状態です。(1.1.2 以降) auto_archive_days を設定すると、マージ済みブランチを n 日後に自動アーカイブできます。

非同期ジョブのポーリングパターン

時間のかかるすべての操作は、url フィールドを含む Job オブジェクトを返します。次のようにポーリングします。

GET <job_url>

Job の status の値は pending、running、completed、errored、failed です。終端状態になるまで待機してください。指数バックオフを使用します（開始は 1 秒、最大 30 秒）。

必要な権限： netbox_branching.sync_branch、netbox_branching.merge_branch、netbox_branching.revert_branch、netbox_branching.archive_branch、netbox_branching.migrate_branch（保留中のマイグレーションの適用）、および recover/ 用の netbox_branching.change_branch（1.2.1 以降）。

ブランチ対応モデル

ほとんどの DCIM、IPAM、Circuits、Tenancy、Virtualization、VPN、Wireless モデルがブランチに対応しています。ブランチ化されないモデル（グローバル／即時反映）：カスタムフィールド、Webhook、イベントルール、エクスポートテンプレート、保存済みフィルター、すべての core.* モデル。

検出エンドポイント： GET /api/plugins/branching/branchable-models/ では、インストール環境でブランチ化されるモデルを正確に確認できます。推測する代わりに、このエンドポイントを使用してください（サポート対象の両方の系列、1.1.x と 1.2.x にあります）。実際には、ほとんどの中核的な運用モデル（DCIM、IPAM、Circuits など）はブランチ化されますが、インフラストラクチャモデル（カスタムフィールド、Webhook、core.*）、branching プラグインと Changes プラグイン自体のモデル、および exempt_models に含まれるモデルはブランチ化されません。他のプラグインの変更履歴が記録されるモデルは、デフォルトでブランチ化されます。

references/branch-aware-models.md を参照してください。

Change Request との統合

NetBox Branching は、変更ワークフローを管理するための netbox-changes プラグインと連携します。

1. netbox-changes で Change Request（CR）を作成します
2. その CR のブランチを作成します
3. ブランチコンテキストで変更を行います
4. レビュー／承認のために CR を提出します
5. CR の承認後にブランチをマージします

連携している場合、関連する CR が承認されていないとマージはブロックされます。REST では、このブロックは 4xx にはなりません。merge/ は 200 と Job を返し、その Job は Merging this branch is not permitted. というエラーになります（UI には理由として No change request has been approved for this branch. と表示されます）。ドライランのマージは制限されません。

組み合わせ： Changes 1.1.3 は、NetBox ≤4.6 では branching 1.1.x と、4.7 では branching 1.2.x と動作します。2 つのプラグインは実行中の NetBox バージョンに合わせる必要があり、一致しない場合、NetBox は起動しません。CR のライフサイクルの詳細については、netbox-changes スキルを参照してください。

アンチパターン

1. 作成後は必ずポーリングする — ブランチは ready になるまで使用できません。provisioning 中に使用すると、400 Selected branch is not ready. が返されます（1.2.2 以降。以前は 500）。レスポンスにはどのブランチかが示されないため、status を確認してください。
2. 古いブランチ — last_sync（同期されたことがない場合は created）が NetBox の CHANGELOG_RETENTION（デフォルトは 90 日）より前のブランチは古くなり、同期できなくなります。同期ジョブは Syncing this branch is not permitted. というエラーになります。REST 表現には is_stale／stale_warning フィールドがありません。now − (last_sync or created) を自分で計算してください。UI は stale_warning_threshold 日前（デフォルトは 7 日）に警告を表示します。保持期間が切れる前に同期するか、アーカイブ／削除してください。
3. ブランチの最大数制限 — プラグイン設定では max_branches（アーカイブされていないブランチの合計数）と max_working_branches が設定されます。上限を超えると、作成は ValidationError で失敗します。
4. アクティブなブランチは削除できない — 先に非アクティブ化してください。
5. マージは全か無か — 検証に失敗すると、トランザクション全体がロールバックされます。
6. 競合には確認が必要 — acknowledge_conflicts: true を渡すまで 409 が返されます。ブランチの値が優先されます。
7. 同期によるカスケード削除 — 親オブジェクトがメインで削除されていた場合、同期時にブランチにのみ存在する子オブジェクトの合成 DELETE レコードが作成されます。
8. スキーマはディスク容量を消費する — 各ブランチはブランチ対応テーブルをすべてコピーします。大規模なデータベースでは、容量を見込んでください。
9. pending-migrations — NetBox のアップグレード後、既存のブランチは使用前にマイグレーションが必要です。
10. DB 権限 — スキーマの作成には、PostgreSQL ユーザーに CREATE ON DATABASE が必要です（NetBox 4.7 では、ltree 拡張機能を自動インストールする際にも同じ権限が必要です）。
11. ?background=true と X-NetBox-Branch を使用した書き込みはメインに行われる（NetBox 4.7.0–4.7.2。4.7.3 で修正済み）— NetBox 4.7 との相互作用を参照してください。
12. プログラムからの書き込みには obj.snapshot() が必要 — ブランチ内のオブジェクトを変更するスクリプト、nbshell、プラグインジョブで、変更前のスナップショットがない場合、prechange_data は空になります。差分に変更前後を表示できず、そのオブジェクトの競合検出は何も行われないままになります。変更前に snapshot() を呼び出してください。

API エンドポイントの概要

エンドポイント	目的
POST /api/plugins/branching/branches/	ブランチを作成
GET /api/plugins/branching/branches/<id>/	ブランチの詳細／ステータス
POST .../branches/<id>/sync/	メインから同期
POST .../branches/<id>/merge/	メインにマージ
POST .../branches/<id>/revert/	マージ済みブランチを元に戻す
POST .../branches/<id>/archive/	マージ済みブランチをアーカイブ（同期し、ブランチを返す）
POST .../branches/<id>/recover/	遷移中のステータスで停止したブランチをリセット（1.2.1 以降）
GET /api/plugins/branching/changes/	ChangeDiff レコード
GET /api/plugins/branching/branch-events/	ブランチイベントログ
GET /api/plugins/branching/branchable-models/	ブランチ対応モデルを検出

NetBox 4.7 との連携

branching 1.2.x が必要です。NetBox 4.7.2 + プラグイン 1.2.1 で検証済みです。

• ?background=true を指定した一括書き込みでは、NetBox 4.7.0–4.7.2 でブランチヘッダーが無視されます。 これらのリリースでは、ホスト／転送ヘッダーのみを保持するスナップショットからワーカー内でリクエストが再構築されるため、X-NetBox-Branch、Cookie、?_branch= が削除されます。その結果、遅延実行される一括書き込みではブランチが有効にならず、main に書き込まれます（または、Changes protect_main が有効な場合は拒否されます）。NetBox 4.7.3 以降では、リクエストヘッダーとクエリー文字列（background を除く。認証はすでに完了しているため、Authorization は削除されます）がワーカーに引き継がれ、ブランチに書き込まれます（netbox-community/netbox#23247）。4.7.2 以前では、?background=true と X-NetBox-Branch を決して併用しないでください。代わりにブランチのコンテキストで同期一括リクエスト（1 回の呼び出しにつき数百件以下のオブジェクト）を送信してください。4.7.3 以降では、他のバックグラウンド書き込みと同様に、ジョブが終了状態になるまでポーリングしてください。
• ブランチ内の階層： NetBox 4.7 では、リージョン／サイトグループ／ロケーション／テナントグループ／モジュールベイのパスは、DB トリガーによって管理される ltree 列に保持されます。1.2.0 では、これらのトリガーが各ブランチのスキーマにインストールされるため、ブランチ内で親を移動または名前変更すると、そのブランチ内の子孫にのみ変更が反映されます。また、マージでは親の変更が再適用されます（main のパスは main のトリガーによって再計算されます）。pg_dump から NetBox 4.7.0 を復元した場合は、新しいブランチを作成する前に、main で rebuild_ltree_paths --check を実行してください。ブランチは main のテーブルとトリガーをそのままコピーします。
• Custom Objects プラグイン ≥ 0.6 は、カスタムオブジェクトのインスタンスのブランチをサポートします（NetBox ではなくプラグインのバージョンで決まります）。0.5.x では、ブランチ内でのインスタンスへの書き込みは拒否されます。netbox-custom-objects を参照してください。
• 一括処理のエラー形式： ブランチのコンテキストで同期一括書き込みが失敗すると、4.7 ではオブジェクトごとの {"detail", "errors": [{"index": N, ...}]} 形式が返されます。これは main と同じ形式です。netbox-api-integration を参照してください。
• NetBox Designs はブランチにデザインをデプロイします。 ブランチを対象としたデザインのデプロイでは、そのブランチにのみ書き込まれます。通常どおり NetBox でブランチをマージまたは削除すると、デプロイもその処理に従います（main に移動するか、Branch gone と表示されます）。netbox-designs を参照してください。
• pynetbox ≥ 7.8.0 には、従来の nb.activate_branch() コンテキストマネージャーに加えて、BranchingExtension（branch.sync()/merge()/revert()/archive()）が含まれています。NetBox 4.7 では ≥ 7.9.0（2026-10-08、Python 3.12 以降）を使用してください。これは 4.7 のサポートを宣言した最初の pynetbox リリースであり、複数選択のカスタムフィールドを持つオブジェクトの保存に関する問題も修正されています。references/api-patterns.md を参照してください。

設定クイックリファレンス

PLUGINS_CONFIG['netbox_branching']。全項目の一覧は、プラグインリポジトリの docs/configuration.md を参照してください。

パラメーター	デフォルト	バージョン	備考
max_branches / max_working_branches	None	0.4 / 0.5	アーカイブ済みでないブランチの合計数／マージ済み・アーカイブ済みでないブランチの上限
exempt_models	[]	0.5	'plugin.model' または 'plugin.*'。ブランチ対象モデルに関連するモデルは除外できません
job_timeout	3600	0.8.2	同期／マージ／復元ジョブのタイムアウト（秒）
stale_warning_threshold	7	0.9	UI で警告を表示する、古い状態になるまでの日数。0 で無効
provision_workers	4	1.1.0	並列コピー／インデックス作成ワーカー。共有 DB では 1～2 に減らしてください
auto_archive_days	None	1.1.2	マージ済みブランチを n 日後に自動アーカイブします（スキーマが削除され、元に戻せなくなります）
auto_recover_stuck_branches	True	1.2.1	停止したワーカーによって孤立したブランチを毎時リセットします
stuck_job_grace_period	300	1.2.1	job_timeout 経過後、実行中のジョブが停止したと判断するまでの猶予秒数
*_validators（sync／merge／migrate／revert／archive）	[]	0.6	アクション前バリデーターのインポートパス

イベントルールの条件、Webhook ペイロード、スクリプトの data で active_branch（id、name、schema_id または null）を利用するには、NetBox の EVENTS_PIPELINE で 'netbox_branching.events.add_branch_context' を extras.events.process_event_queue より前に追加してください。

バージョンに関する注意事項

NetBox 4.7.3（2026-10-13）

• ?background=true の一括書き込みで X-NetBox-Branch／?_branch= がワーカーに引き継がれるようになり、書き込みがブランチに反映されます（#23247。4.7.0～4.7.2 ではメインに反映されていました）。4.7.3 以降を実行してください。

プラグイン 1.2.x — NetBox 4.7 のみ（2026-09-02）

• 1.2.0： ltree と非正規化トリガーがブランチスキーマにも複製されるようになりました。NetBox ≥ 4.7.0 が必要です。4.7.3 以降を実行してください（4.7.0／4.7.1 では、バックグラウンドの一括リクエストで作成された平文トークンがジョブ結果に漏れていました。4.7.3 ではブランチヘッダーがバックグラウンドの一括ジョブに引き継がれ、config-context の omit 最適化も復元されています）。
• 1.2.1： 停止したブランチの復旧機能 — recover/ エンドポイント、auto_recover_stuck_branches、stuck_job_grace_period。復元時に削除済みオブジェクトを復元する ObjectChange.undo() の修正。
• 1.2.2（2026-10-08）：squash merge または復元後のケーブルパス再計算（#469）、基盤となる検証エラーを含むマージ失敗レポート（#632）、ブランチの同期時における競合ベースラインの更新（#640）、squash merge 中の循環 DELETE 依存関係の解消（#668）、レコード削除前のブランチのプロビジョニング解除（#641）、プラグインがインストールされていない場合にスクリプトがブランチを有効化しないよう修正（#649）。

プラグイン 1.1.x — NetBox 4.4.1～4.6.x（2026-06～2026-08）

• 1.1.0： 並列プロビジョニング（provision_workers）。大規模 DB で最大約 4 倍高速化します。
• 1.1.1： squash merge で任意の長さの FK 循環を解消。MPTT コンポーネントモデル（モジュールベイ、インベントリーアイテム）の反復マージを修正。
• 1.1.2： auto_archive_days。
• 1.1.3： オブジェクト更新時の競合が ChangeDiff に記録されるようになりました（以前は一部の更新競合が検出されていませんでした）。

プラグイン 1.0.x（旧バージョン）

• 1.0.4：同期時の競合解決がマージ時にも保持されるようになりました。変更ログに記録されないモデル向けのプラグインリゾルバーフックを追加。1.0.5：変更されていない JSON 辞書キーがマージ時に保持されるようになりました。1.0.x の全バージョンから、1.1.3（≤4.6）または 1.2.2（4.7）にアップグレードしてください。

参考資料

• references/branch-lifecycle.md — 11 の状態とすべての遷移を含む完全な状態遷移図
• references/api-patterns.md — すべての操作に関する完全な API 例
• references/conflict-resolution.md — 競合検出、3 者間差分、確認
• references/branch-aware-models.md — ブランチ対象、除外対象、検出方法