netbox-change-control 0.6.0

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.

How it works | Documentation | Features | Requirements | Quick install

How it works

1. Someone creates a branch and makes their changes inside it, as normal for netbox-branching.
2. They open a change request against that branch.
3. 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.
4. Each policy contains rules. A rule says how many approvals it needs and who may give them.
5. Reviewers approve, request changes, or comment. They can also comment on one specific changed object.
6. Independently, the pre-merge checks named by those policies run. A required check that is not passing blocks the merge on its own.
7. Once every rule is satisfied and every required check passes, the merge button appears.
8. 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.

Documentation

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.

To read the site on your own machine, install Zensical and run zensical serve at the root of a checkout.

Features

Requirements

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.

Quick install

# 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_control

See Installation and configuration for the detail, including why exempt_models is not optional.