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 server	如果已配置 — 查询现有变更请求	实时 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 之上添加了类似代码审查的工作流。每个分支都可以有一个变更请求（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-branching 版本与 NetBox 版本匹配——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（同一时间只能有一个活动 CR），被拒绝的 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

插件 v1.0+：一个分支在生命周期内可以有多个变更请求，但同一时间只能有一个活动 CR（状态不是 completed 或 rejected）。为某个分支创建第二个活动 CR 会失败，并引发 ValidationError："This branch already has an active change request." 一旦 CR 状态变为 rejected 或 completed，名额就会释放——你可以为同一分支新建 CR（或重新打开被拒绝的 CR）。删除分支会级联删除 CR。

（在 0.4.x 中，分支与 CR 严格一对一，创建第二个 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。

创建变更请求

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 是分支的主键（必须存在，且不能已有活动 CR）
• policy 是必填项（v1.0+）——每个 CR 都必须有一个非空外键；不带 policy 的 POST 会失败。（此字段也会影响合并门控。）
• (1.1.0+) 标记为 is_default: true 的策略（最多一个）仅会在 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

策略系统

一个策略包含一个或多个 PolicyRules。所有启用的规则都必须通过，策略才算满足。

策略字段 (1.1.0+)

• is_default — 在 UI 的 CR 表单中预选；最多只能有一个策略（验证错误 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 — 跳过已禁用的规则

重要注意事项：零条规则 = 始终失败

启用规则为零条的策略始终返回 False。必须至少创建一条已启用的 PolicyRule，CR 才能达到 approved 状态。

策略设置示例和评估详情请参阅 references/policy-system.md。

合并门禁

安装插件后，合并门禁始终处于启用状态——没有配置开关。每次分支合并都需要已批准的 CR。

如果尝试合并没有已批准 CR 的分支，UI 会显示 No change request has been approved for this branch.。通过 REST 调用时，分支 merge/ 端点仍会返回 200 + Job；随后 job 会报错： Merging this branch is not permitted.——请轮询 job，不要只看 200 响应。 试运行合并（"commit": false）不受门禁限制。

protect_main

默认禁用。 启用后，除非用户拥有绕过权限，否则会阻止直接写入可感知分支的模型。所有更改都必须通过分支进行。

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

• 绕过权限（v1.0+）： 在 Policy 对象上授予自定义操作 bypass（在对象权限表单中选择 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 会用上述错误拒绝请求——请检查 job，请求本身会返回 202。在此版本中，请在分支上下文中使用同步批量写入。(NetBox 4.7.3+) 标头和查询字符串会传递到 job，因此后台批量写入会写入分支。

详情请参阅 references/protect-main.md。

完整工作流

1. 创建分支（通过 netbox-branching API）
2. 等待分支状态变为 READY
3. 创建与分支关联的 CR，并指定策略
4. 在分支上下文中进行更改（X-NetBox-Branch 标头）
5. 将 CR 状态设为 needs-review（或创建时就设为 needs-review）
6. 审阅者提交状态为 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. 零规则策略——始终会失败。至少添加一条已启用的规则。
4. 每个分支只能有一个活动 CR（v1.0+）——第二个活动 CR 会导致 ValidationError；已拒绝或已完成的 CR 会释放名额。
5. 合并门禁是强制的——没有开关，安装插件后始终启用
6. protect_main 默认关闭——必须在配置中显式启用
7. 不能手动设置 approved——只有满足策略条件后才能达到此状态
8. 默认策略仅适用于 UI (1.1.0+)——API 不会自动填入 policy；请查找 ?is_default=true 并传入该策略
9. require_independent_review 下的自我批准 (1.1.0+)——所有者的 approved 审阅会被记录，但不会被采纳；如果某条规则的唯一合格审阅者是所有者，该所有者永远无法满足此规则
10. 不要 POST 审阅状态 pending——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": [...]}），而不是插件消息。请修复那些依赖旧插件错误文本进行匹配的客户端

版本说明

插件 1.1.3（2026-09-09）— NetBox 4.5.2–4.7

• 支持 NetBox 4.7。插件不再预先验证格式错误的批量请求（参见反模式 12）。NetBox 4.7 需要使用 1.2.x 分支，≤4.6 则使用 1.1.x 分支。

插件 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，使其能在分支架构中顺利应用。

插件 1.0.x（2026-05 → 2026-06）

• **1.0.0：**每个分支允许多个 CR（仅一个处于活动状态）、重新打开被拒绝的 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 不再将分支范围内的后台写入误判为对主分支的写入。请运行 ≥ 4.7.3（4.7.0/4.7.1 会将令牌明文泄漏到作业结果中；4.7.3 添加了分支安全的后台写入和配置上下文省略优化）。

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 配置和行为