Policy-driven change control and mandatory review for NetBox branches
change requests • policies • checks • comments
Documentation | Install | Compatibility | Policies | Checks | Changelog
This plugin builds on netbox-branching. A branch stages your changes; this plugin decides who must approve them and refuses the merge until they have.
The goal is change control that is policy driven: who must approve a change is decided by the objects it touches, not by whoever opened it. Around that sit two extension points, so the same gate can be driven by more than people. Pre-merge checks are pluggable, and an event fires on every status change, so a change request can call an external system, wait for a CI result, or ask a model to review the diff before anyone merges it. See writing your own checks, which includes an AI reviewer and a CI reporter.
It takes ideas from NetBox Labs change management, for policies and rules governing who must review a branch; from GitHub, for status checks that gate a merge independently of human approval and for review comments anchored to a specific change; and from Infrahub by OpsMill, for treating a proposed change as a first-class object that carries its own validation.
Note
Independent community plugin. Free, MIT licensed, not official, not certified and not endorsed by NetBox Labs. It bundles no netbox-branching code. You install that package yourself, and its own licence governs how you may use it.
No commercial support. If you need a supported product, use the NetBox Labs change management plugin.
Warning
Not stable yet. The version is below 1.0. Models, settings and the REST API can still change between releases. Read the changelog before you upgrade.
How it works | Documentation | Features | Requirements | Quick install
- Someone creates a branch and makes their changes inside it, as normal for netbox-branching.
- They open a change request against that branch.
- The plugin reads which object types the branch touches and attaches every policy whose scope matches. A policy can narrow further on the values of the objects themselves. The author cannot remove them.
- Each policy contains rules. A rule says how many approvals it needs and who may give them.
- Reviewers approve, request changes, or comment. They can also comment on one specific changed object.
- Independently, the pre-merge checks named by those policies run. A required check that is not passing blocks the merge on its own.
- Once every rule is satisfied and every required check passes, the merge button appears.
- After the merge, the request is marked completed.
Two gates guard the merge and they are independent: the people gate (policies and reviews) and the machine gate (checks). A change can be approved by every reviewer and still be refused by a check.
The documentation is a website: antoinekh.github.io/netbox-change-control. Its sources are the Markdown files in docs/, built with Zensical and published by GitHub Actions on every push to master.
| Page | Covers |
|---|---|
| Installation and configuration | Requirements, installing, and every setting. |
| Compatibility matrix | Which release runs on which NetBox and which netbox-branching. |
| Policies and rules | Scoping a policy and writing rules. |
| Policy conditions | Narrowing a policy on object values. |
| Conflicts with main | What counts as a real conflict, and how to resolve one. |
| Change requests | The lifecycle, and what survives a branch deletion. |
| Reviews | Submitting reviews and commenting on individual changes. |
| Pre-merge checks | What checks are and which ship built in. |
| Writing your own checks | The registry, an AI reviewer, and reporting from CI. |
| Event rules | Firing a webhook or a script on a change request. |
| Merging, windows and auto-merge | Change windows and automatic merging. |
| Protecting main | Requiring a branch, optionally for part of NetBox only. |
| Automatic behaviours | Stale reviews, reevaluation, notifications. |
| Administration guide | Roles, the permission matrix, building policies, troubleshooting. |
| Permissions | The short reference for every permission name. |
| REST API | Every endpoint. |
| Extending this plugin | How another plugin adds content and checks. |
| Design | Why it is built this way. |
To read the site on your own machine, install Zensical and run zensical serve at the root of a checkout.
| Feature | Status |
|---|---|
| Policies containing rules with a minimum approval count | Done |
| Rules naming reviewer groups and individual reviewers | Done |
| Policies attached automatically, scope-matched from the branch contents, following it as it changes, and not selectable by the author | Done |
| Policy conditions, narrowing a policy on the values of the changed objects | Done |
| Change requests with status and priority | Done |
| Reviews with approve, request changes, and comment | Done |
| Per-change comments on the branch diff, with threaded replies, in Markdown | Done |
| Merge button appears once approved | Done, on the change request and on the branch |
| Status set to completed after a successful merge | Done |
Pre-merge gate, enforced regardless of protect_main |
Done |
protect_main blocks direct edits outside a branch, optionally scoped |
Done, with a bypass permission |
| Stale review detection when the branch changes | Done |
| Approval invalidation when the branch changes after approval | Done |
| Policy reevaluation on rule, reviewer or group membership change | Done |
| Real conflicts with main, distinguished from a stale branching baseline | Done |
| Notifications to reviewers | Done, through NetBox's notification inbox |
| Pluggable pre-merge checks, in-process or reported over the REST API | Done |
| Change windows, with an override permission | Done |
| Automatic merge once every gate is satisfied | Done |
| Change request survives deletion of its branch | Done |
| REST API for every model | Done |
| Component | Version |
|---|---|
| NetBox | >= 4.7.0, < 4.8 |
| netbox-branching | >= 1.2, < 1.3 |
| Python | >= 3.12 |
This is the NetBox 4.7 line. For NetBox 4.6, stay on the 0.4.x line; the two do not overlap, because netbox-branching 1.1.x and 1.2 do not either. The compatibility matrix has every release, and Installation covers moving between the two lines.
# configuration/plugins.py
PLUGINS = [
'netbox_change_control',
'netbox_branching', # must stay last
]
PLUGINS_CONFIG = {
'netbox_branching': {
'exempt_models': ['netbox_change_control.*'], # required
},
}./manage.py migrate netbox_change_controlSee Installation and configuration for the detail, including why exempt_models is not optional.