netbox-changes

NetBox Changes — 変更リクエスト管理

NetBox Changes に関する知識は古くなっている可能性があります。 CR のライフサイクル、ポリシーの適用、API の動作は、プラグインのリリースごとに変化します。事前学習済みの知識より、情報の取得を優先してください。

情報取得元

情報源	URL / 方法	用途
Changes のドキュメント	https://netboxlabs.com/docs/developer/plugins-extensions/changes/	設定、モデル、ライフサイクル
Changes のモデル	https://netboxlabs.com/docs/developer/plugins-extensions/changes/models/changerequest/	CR のフィールドと状態
NetBox MCP サーバー	設定されている場合 — 既存の変更リクエストを照会	リアルタイムの CR 状態
NetBox Platform MCP	設定されている場合 — CR のライフサイクル全体にわたる操作	CR の作成、レビュー、承認

最初に：接続を確認

Changes プラグインがインストールされていることを確認してください。

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

404 が返された場合、netbox_changes プラグインはインストールされていません。403 の場合、トークンに必要な権限がありません。

---

netbox_changes プラグインは、NetBox Branching 上にコードレビュー形式のワークフローを追加します。各ブランチには 1 つの変更リクエスト（CR）を関連付けられ、ポリシーとレビューを通じてマージを制御します。

プラグイン： netbox_changes 1.1.x（最新 v1.1.3、2026-09-09） · NetBox： 4.5.2–4.7（1.0.2 で最低バージョンが 4.4 から 4.5.2 に引き上げられ、1.1.3 で 4.7 が追加されました） · ベース URL： /api/plugins/changes/

branching との組み合わせ： Changes には、NetBox のバージョンに対応する netbox-branching が必要です。NetBox 4.5.2–4.6 では branching 1.1.x、NetBox 4.7 では branching 1.2.x を使用してください。バージョンが一致しないと NetBox が起動しません。netbox-branching を参照してください。

プラグイン v1.0 以降では、0.4.x 系と比べて CR のライフサイクルの仕様が変更されています。ブランチには複数の CR を作成できますが、同時にアクティブにできるのは 1 つだけです。却下された CR は再オープンまたは置き換えが可能で、policy は必須となり、ポリシーが未達成の状態でも changes-requested を設定できます。v1.1.0 ではポリシーごとの is_default と require_independent_review が追加されました。以下に該当箇所を記載しています。バージョンに関する注意を参照してください。

クイックリファレンス

エンドポイント

パス	目的
change-requests/	CR の CRUD とステータス管理
reviews/	レビューの送信／一覧取得
policies/	レビューポリシー
policy-rules/	ポリシー内のルール
comments/	CR のコメント
comment-replies/	スレッド形式の返信
change-requests/<id>/retrigger/ (POST)	CR のイベントルールを再発行（event_retriggered）。change 権限と書き込み可能なトークンが必要

CR のステータス（正確な値）

draft · needs-review · changes-requested · approved · completed · rejected

レビューのステータス

pending · comment · changes-requested · approved · rejected

pending は「レビューが要求されたが、まだ送信されていない」ことを示すプレースホルダーです。POST で送信しないでください。レビューのフォームでは非表示になり（1.1.1 以降）、REST API は pending is not a valid status for a submitted review. というエラーで拒否します。

主な概念

ブランチごとにアクティブな CR は 1 つ

プラグイン v1.0 以降： ブランチには、時間の経過とともに複数の変更リクエストを作成できますが、同時にアクティブにできるのは 1 つだけです（completed または rejected 以外のステータス）。ブランチに 2 つ目のアクティブな CR を作成すると、ValidationError が発生し、"This branch already has an active change request." が表示されます。CR が rejected または completed になると枠が空き、同じブランチで新しい CR を作成するか、却下された CR を再オープンできます。ブランチを削除すると、関連する CR も連鎖して削除されます。

（0.4.x ではブランチと CR の関係は厳密な一対一であり、2 つ目の CR を作成すると IntegrityError が発生しました。v1.0 以降ではこの仕様を前提にしないでください。）

作成者／所有者のフィールドは読み取り専用

ChangeRequest.owner、Review.user、Comment.author、CommentReply.author はすべて、現在のユーザーに自動で設定されます。POST 本文に含めないでください。指定しても無視されます。

CR のライフサイクル

状態遷移図

CREATE ──→ draft ──→ needs-review ←─────────────────┐
                        │    ↑                       │
                        │    │ (new changes or        │
                        │    │  policy rule change)   │
                        ▼    │                       │
                 changes-requested ──────────────────┘
                        │
                        ▼
                    approved
                        │
                  [branch merge]
                        │
                        ▼
                    completed

Any active status ──→ rejected (manual)

新しい CR は draft または needs-review としてのみ作成できます。

ステータスの自動遷移

ほとんどの遷移は自動的に発生します。

トリガー	遷移元 → 遷移先
レビューが送信され、ポリシーの条件を満たした	needs-review/changes-requested → approved
changes-requested のレビュー	有効な任意のステータス → changes-requested
ブランチに新しい変更が加えられた	approved/changes-requested → needs-review
ブランチがマージされた	approved → completed（実際の変更を含むマージが正常に完了する必要があります）
ポリシールールが変更または削除され、ポリシーの条件を満たさなくなった	approved → needs-review

手動での遷移： ポリシーの条件を満たしていない場合、ユーザーは draft、needs-review、changes-requested、または rejected を直接設定できます（有効な手動設定値は draft / needs-review / changes-requested / rejected です）。approved を手動で設定することはできません。ポリシーの条件を満たした場合にのみ設定できます。completed はマージ時にのみ自動で設定されます。レビュー担当者が「changes-requested」のレビューを送信すると、CR のステータスも changes-requested に変わります。

Plugin v1.0+：ポリシーの条件を満たしていない場合でも、changes-requested が有効な手動ステータスになりました（0.4.x では自動設定のみでした）。rejected の CR は行き止まりではなくなりました。再オープン（draft/needs-review に戻す）することも、同じブランチで新しい CR に置き換えることもできます。

遷移表の全容については、references/cr-lifecycle.md を参照してください。

Change Request の作成

POST /api/plugins/changes/change-requests/
{
    "name": "Add new switches",
    "branch": 123,
    "policy": 1,
    "status": "needs-review",
    "priority": 3,
    "summary": "Adding new switches to DC1"
}

• owner は自動設定されるため、含めないでください
• branch はブランチの PK です（存在している必要があり、すでに有効な CR が存在していてはいけません）
• policy は必須です（v1.0+）。すべての CR において null 以外の FK であり、policy を指定しない POST は失敗します。（マージのゲート制御にも使用されます。）
• (1.1.0+) is_default: true に設定されたポリシー（最大 1 つ）は、UI フォームでのみ事前選択されます。REST API では自動設定されません。GET /api/plugins/changes/policies/?is_default=true で取得し、その id を渡してください。
• priority は整数です（1=低、5=高）

レビューワークフロー

レビューの送信

POST /api/plugins/changes/reviews/
{
    "change_request": 1,
    "status": "approved",
    "comments": "LGTM"
}

user フィールドには現在のユーザーが自動設定されます。送信しないでください。

古いレビューの追跡

レビューでは、確認済みの変更が記録されます。レビュー後に新しい変更が加えられると、そのレビューは古いものとなり、再送信が必要になる場合があります。

• 古いレビューはポリシーの評価対象になりません
• ユーザーごとに、最新の古くないレビューのみが考慮されます
• 承認後に変更が加えられると、CR は needs-review に戻り、レビュー担当者は再承認する必要があります

レビューの反復パターン

1. レビュー担当者が changes-requested を送信 → CR のステータスが changes-requested になる
2. 作成者がブランチで修正を行う → CR が needs-review に戻る（古くなった承認は無効になります）
3. レビュー担当者が再レビューして approved を送信 → ポリシーの条件を満たしていれば、CR は approved になる

ポリシーシステム

Policy には 1 つ以上の PolicyRules が含まれます。ポリシーを満たすには、有効なルールがすべて合格する必要があります。

ポリシーフィールド (1.1.0+)

• is_default — UI の CR フォームで事前選択されます。ポリシーは最大 1 つです（バリデーションエラー A default policy already exists: <name>.）。REST API には影響しません。
• require_independent_review — CR 所有者自身のレビューは、このポリシーのルールの評価対象になりません。所有者は引き続きレビューを投稿できます（記録されますが、除外されます）。所有者がルールの唯一の対象レビュー担当者である場合、その所有者の CR ではルールを満たせません。デフォルトは false です（1.0.x と同様に、所有者のレビューもカウントされます）。

PolicyRule のフィールド

• min_reviews — 必要な承認済み（古くない）レビューの最小数。0～10。0 にするとルールは常に合格します（推奨されません）。
• reviewers — 特定のユーザーとの M2M
• reviewer_groups — グループとの M2M
• reviewers ∪ reviewer_groups のメンバーであるユーザーのレビューのみがカウントされます
• enabled — 無効なルールはスキップされます

重要な注意点：ルールが 0 件の場合は常に不合格

有効なルールが0 件のポリシーは、常に False を返します。CR が approved に到達するには、少なくとも 1 つの有効な PolicyRule を作成する必要があります。

設定例と評価の詳細については、references/policy-system.md を参照してください。

マージゲーティング

プラグインのインストール中は、マージゲーティングが常に有効です。設定で切り替えることはできません。ブランチをマージするには、承認済みの CR が必要です。

承認済みの CR がないブランチをマージしようとすると、UI に No change request has been approved for this branch. と表示されます。REST 経由では、ブランチングの merge/ エンドポイントは引き続き 200 + Job を返しますが、その後 ジョブ が Merging this branch is not permitted. というエラーになります。200 を信用せず、ジョブをポーリングしてください。 ドライランマージ（"commit": false）ではゲートが適用されません。

protect_main

デフォルトでは無効です。 有効にすると、バイパス権限を持つユーザーを除き、ブランチ対応モデルへの直接書き込みがブロックされます。すべての変更はブランチ経由で行う必要があります。

# netbox config
PLUGINS_CONFIG = {
    'netbox_changes': {
        'protect_main': True,
    }
}

• バイパス権限（v1.0+）： Policy オブジェクトにカスタムアクション bypass を付与します（ObjectPermission フォームの NetBox Change Management → Policy）。スーパーユーザーには暗黙的に付与されます。単一のフラットな権限文字列ではなく、「Policy の bypass アクション」と説明してください。内部的なコード名は bypass ですが、強制チェックでは引き続き bypass_policy が参照されます。
• ブランチのマージ／リバート中は、protect_main が一時的に停止されます。
• ブロック時のエラー："Changes directly to main are not permitted."
• (NetBox 4.7.0–4.7.2) ?background=true を指定した一括書き込みは、X-NetBox-Branch を付けて送信しても、アクティブなブランチがないワーカーで実行されます（ヘッダーはジョブに引き継がれません）。そのため、protect_main によって上記のエラーで拒否されます。リクエスト自体は 202 を返すため、ジョブを確認してください。このバージョンでは、ブランチコンテキストで同期一括書き込みを使用してください。(NetBox 4.7.3+) ヘッダーとクエリー文字列がジョブに引き継がれるため、バックグラウンド一括書き込みはブランチに反映されます。

詳細は references/protect-main.md を参照してください。

完全なワークフロー

1. ブランチを作成する（netbox-branching API 経由）
2. ブランチのステータスが READY になるまで待つ
3. ポリシーを指定して、ブランチにリンクされた CR を作成する
4. ブランチコンテキスト（X-NetBox-Branch ヘッダー）で変更を加える
5. CR を needs-review にする（または needs-review として作成する）
6. レビュアーが status: approved でレビューを送信する
7. ポリシーの条件を満たす → CR は自動的に approved に遷移する
8. ブランチをマージする → マージゲーティングが承認済み CR を確認し、マージが進行する
9. CR は自動的に completed に遷移する

protect_main=True の場合、ステップ 4 が強制され、ブランチがなければ変更できません。

よく使うフィルター

GET /api/plugins/changes/change-requests/?status=needs-review
GET /api/plugins/changes/change-requests/?owner=admin
GET /api/plugins/changes/change-requests/?branch=feature-branch
GET /api/plugins/changes/reviews/?change_request_id=1&status=approved
GET /api/plugins/changes/policy-rules/?policy_id=1

アンチパターン

1. ステータス名にはハイフンを使用します：needs-review、changes-requested（アンダースコアではありません）
2. Owner/user/author フィールドは読み取り専用で、自動的に設定されます。POST しないでください。
3. ルールが 0 件のポリシーは常に失敗します。有効なルールを少なくとも 1 つ追加してください。
4. 1 つのブランチにつき、アクティブな CR は 1 件のみ（v1.0+）— 2 件目のアクティブな CR は ValidationError で失敗します。却下済み／完了済みの CR がある場合は、その枠を再利用できます。
5. マージゲーティングは必須です — 切り替えられず、プラグインのインストール中は常に有効です
6. protect_main はデフォルトで OFF です — 設定で明示的に有効にする必要があります
7. approved は手動で設定できません — ポリシーの条件を満たした場合にのみ到達できます
8. デフォルトポリシーは UI でのみ適用されます (1.1.0+) — API は policy を自動入力しません。?is_default=true で検索し、値を渡してください
9. require_independent_review が有効な場合の自己承認 (1.1.0+) — オーナーの approved レビューは記録されますが、無視されます。対象となるレビュアーがオーナーだけのルールは、そのオーナーに対しては決して合格になりません
10. レビューのステータスに pending を指定して POST しないでください — API に拒否されます
11. 自分のレビュー、コメント、返信のみ編集／削除できます (1.0.2+) — 一括 PATCH/DELETE 経由の場合も同様です（403 You can only modify your own objects.）。スーパーユーザーも例外ではありません
12. 不正な一括リクエスト本文 (1.1.3+) — 有効な {"id": ...} オブジェクトのリストではない一括 PATCH/DELETE 本文は、サポート対象のすべての NetBox バージョンで NetBox 独自の一括処理ハンドラーに渡されるようになりました。そのため、エラーはプラグインのメッセージではなく NetBox のものになります（4.7 ではオブジェクトごとの {"detail", "errors": [...]}）。古いプラグインエラーテキストに一致するよう実装されたクライアントを修正してください

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

Plugin 1.1.3 (2026-09-09) — NetBox 4.5.2–4.7

• NetBox 4.7 に対応しました。不正な一括リクエストは、プラグインによる事前検証の対象外になりました（アンチパターン 12 を参照）。4.7 では 1.2.x ブランチ、≤4.6 では 1.1.x ブランチが必要です。

Plugin 1.1.0–1.1.2 (2026-06 → 2026-07) — NetBox 4.5.2–4.6

• 1.1.0： Policy.is_default（UI での事前選択）、Policy.require_independent_review、view_policy／view_policyrule がない場合に Policies／Policy Rules のナビゲーションを非表示、CR 詳細ページへの変更概要の表示、ステータス／優先度のヘルプツールチップ。
• 1.1.1： レビューフォームで pending を送信できないようにしました。NetBox 4.5.x のマイグレーション互換性の修正。
• 1.1.2： ブランチのスキーマに正常に適用されるよう、マイグレーションを fake_on_branch に設定しました。

Plugin 1.0.x (2026-05 → 2026-06)

• 1.0.0： ブランチごとに複数の CR（アクティブなものは 1 つ）、却下された CR の再オープン、bypass 権限、オーナーへの通知、retrigger/ アクション、CR の Webhook ペイロードへの context.last_branch_change の追加。
• 1.0.2： NetBox 4.5.2 以降が最低要件です。レビュー、コメント、返信の編集／削除はオーナーに制限されます（一括操作でも同様）。解決／未解決にするには change_comment が必要です。

NetBox 4.7.3 (2026-10-13)

• ?background=true による一括書き込みでは、X-NetBox-Branch／?_branch= がワーカーに引き継がれるため、protect_main がブランチ対象のバックグラウンド書き込みを main への書き込みとして拒否しなくなりました。4.7.3 以降を実行してください（4.7.0／4.7.1 ではジョブの結果にトークンの平文が漏れていました。4.7.3 ではブランチに対応したバックグラウンド書き込みと、config-context の omit 最適化が追加されています）。

NetBox 4.7 (2026-09-02) — CR 自動化での変更点

• イベントルールの条件に changed／unchanged と snapshots.prechange.* のパスが追加されました。保存のたびに実行するのではなく、CR が承認済みになったときだけ実行できます。references/api-patterns.md を参照してください。
• Webhook コンテキストキー username と request_id は削除されました。本文テンプレートでは request.user／request.id を使用してください。
• オブジェクトごとの一括エラーと ?background=true（4.7.0～4.7.2 ではブランチヘッダーが失われるため、そこでブランチ内では使用しないでください。4.7.3 以降では引き継がれます。上記の protect_main を参照）。

参考資料

• references/cr-lifecycle.md — すべての遷移を含む完全な状態マシン
• references/api-patterns.md — すべてのエンドポイントの完全な API 例
• references/policy-system.md — ポリシーとルールの設定
• references/protect-main.md — protect_main の設定と動作