netbox-change-control 0.3.0__tar.gz

netbox_change_control-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Keranflech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netbox_change_control-0.3.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: netbox-change-control
+Version: 0.3.0
+Summary: Policy-driven change control and mandatory review for NetBox branches
+Author-email: Antoine Keranflech <antoine.keranflech@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/antoinekh/netbox-change-control
+Project-URL: Documentation, https://github.com/antoinekh/netbox-change-control/blob/master/docs/index.md
+Project-URL: Source, https://github.com/antoinekh/netbox-change-control
+Project-URL: Changelog, https://github.com/antoinekh/netbox-change-control/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/antoinekh/netbox-change-control/issues
+Keywords: netbox,netbox-plugin,change-management,change-control,branching,approval-workflow,network-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: System Administrators
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: netboxlabs-netbox-branching<1.2,>=1.1.3
+Dynamic: license-file
+
+<div align="center">
+  <img src="docs/img/logo.svg" width="460" alt="netbox change control" />
+  <p><strong>Policy-driven change control and mandatory review for NetBox branches</strong></p>
+  <p>change requests &bull; policies &bull; checks &bull; comments</p>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
+  <img src="https://img.shields.io/badge/NetBox-%3E%3D%204.6.9%2C%20%3C%204.7-00857d" alt="NetBox compatibility" />
+  <img src="https://img.shields.io/badge/netbox--branching-%3E%3D%201.1.3-00857d" alt="netbox-branching compatibility" />
+  <img src="https://img.shields.io/badge/python-%3E%3D%203.12-blue" alt="Python version" />
+  <p>
+    <strong><a href="docs/index.md">Documentation</a></strong> |
+    <strong><a href="docs/installation.md">Install</a></strong> |
+    <strong><a href="docs/policies.md">Policies</a></strong> |
+    <strong><a href="docs/checks.md">Checks</a></strong> |
+    <strong><a href="CHANGELOG.md">Changelog</a></strong>
+  </p>
+</div>
+
+This plugin builds on [netbox-branching](https://github.com/netboxlabs/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](docs/custom-checks.md), which includes an AI reviewer and a CI reporter.
+
+It takes ideas from **[NetBox Labs change management](https://netboxlabs.com/docs/changes/)**, 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](https://docs.infrahub.app/topics/proposed-change)** 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](https://netboxlabs.com/docs/changes/) 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](CHANGELOG.md) before you upgrade.
+
+<p align="center">
+  <a href="#how-it-works">How it works</a> |
+  <a href="#documentation">Documentation</a> |
+  <a href="#features">Features</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#quick-install">Quick install</a>
+</p>
+
+<p align="center">
+  <img src="docs/img/change-request-detail.png" width="800" alt="A change request, showing the approval status, the pre-merge checks and the conflict banner" />
+</p>
+
+## 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
+
+Full documentation is in [`docs/`](docs/index.md).
+
+| Page | Covers |
+|---|---|
+| [Installation and configuration](docs/installation.md) | Requirements, installing, and every setting. |
+| [Policies and rules](docs/policies.md) | Scoping a policy and writing rules. |
+| [Policy conditions](docs/policy-conditions.md) | Narrowing a policy on object values. |
+| [Conflicts with main](docs/conflicts.md) | What counts as a real conflict, and how to resolve one. |
+| [Change requests](docs/change-requests.md) | The lifecycle, and what survives a branch deletion. |
+| [Reviews](docs/reviews.md) | Submitting reviews and commenting on individual changes. |
+| [Pre-merge checks](docs/checks.md) | What checks are and which ship built in. |
+| [Writing your own checks](docs/custom-checks.md) | The registry, an AI reviewer, and reporting from CI. |
+| [Event rules](docs/event-rules.md) | Firing a webhook or a script on a change request. |
+| [Merging, windows and auto-merge](docs/merging.md) | Change windows and automatic merging. |
+| [Protecting main](docs/protect-main.md) | Requiring a branch, optionally for part of NetBox only. |
+| [Automatic behaviours](docs/automation.md) | Stale reviews, reevaluation, notifications. |
+| [Administration guide](docs/admin-guide.md) | Roles, the permission matrix, building policies, troubleshooting. |
+| [Permissions](docs/permissions.md) | The short reference for every permission name. |
+| [REST API](docs/api.md) | Every endpoint. |
+| [Extending this plugin](docs/extending.md) | How another plugin adds content and checks. |
+| [Design](docs/design.md) | Why it is built this way. |
+
+## Features
+
+| 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 |
+
+## Requirements
+
+| Component | Version |
+|---|---|
+| NetBox | `>= 4.6.9, < 4.7` |
+| netbox-branching | `>= 1.1.3, < 1.2` |
+| Python | `>= 3.12` |
+
+## Quick install
+
+```python
+# configuration/plugins.py
+PLUGINS = [
+    'netbox_change_control',
+    'netbox_branching',          # must stay last
+]
+
+PLUGINS_CONFIG = {
+    'netbox_branching': {
+        'exempt_models': ['netbox_change_control.*'],   # required
+    },
+}
+```
+
+```bash
+./manage.py migrate netbox_change_control
+```
+
+See [Installation and configuration](docs/installation.md) for the detail, including why `exempt_models` is not optional.

netbox_change_control-0.3.0/README.md

@@ -0,0 +1,135 @@
+<div align="center">
+  <img src="docs/img/logo.svg" width="460" alt="netbox change control" />
+  <p><strong>Policy-driven change control and mandatory review for NetBox branches</strong></p>
+  <p>change requests &bull; policies &bull; checks &bull; comments</p>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
+  <img src="https://img.shields.io/badge/NetBox-%3E%3D%204.6.9%2C%20%3C%204.7-00857d" alt="NetBox compatibility" />
+  <img src="https://img.shields.io/badge/netbox--branching-%3E%3D%201.1.3-00857d" alt="netbox-branching compatibility" />
+  <img src="https://img.shields.io/badge/python-%3E%3D%203.12-blue" alt="Python version" />
+  <p>
+    <strong><a href="docs/index.md">Documentation</a></strong> |
+    <strong><a href="docs/installation.md">Install</a></strong> |
+    <strong><a href="docs/policies.md">Policies</a></strong> |
+    <strong><a href="docs/checks.md">Checks</a></strong> |
+    <strong><a href="CHANGELOG.md">Changelog</a></strong>
+  </p>
+</div>
+
+This plugin builds on [netbox-branching](https://github.com/netboxlabs/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](docs/custom-checks.md), which includes an AI reviewer and a CI reporter.
+
+It takes ideas from **[NetBox Labs change management](https://netboxlabs.com/docs/changes/)**, 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](https://docs.infrahub.app/topics/proposed-change)** 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](https://netboxlabs.com/docs/changes/) 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](CHANGELOG.md) before you upgrade.
+
+<p align="center">
+  <a href="#how-it-works">How it works</a> |
+  <a href="#documentation">Documentation</a> |
+  <a href="#features">Features</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#quick-install">Quick install</a>
+</p>
+
+<p align="center">
+  <img src="docs/img/change-request-detail.png" width="800" alt="A change request, showing the approval status, the pre-merge checks and the conflict banner" />
+</p>
+
+## 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
+
+Full documentation is in [`docs/`](docs/index.md).
+
+| Page | Covers |
+|---|---|
+| [Installation and configuration](docs/installation.md) | Requirements, installing, and every setting. |
+| [Policies and rules](docs/policies.md) | Scoping a policy and writing rules. |
+| [Policy conditions](docs/policy-conditions.md) | Narrowing a policy on object values. |
+| [Conflicts with main](docs/conflicts.md) | What counts as a real conflict, and how to resolve one. |
+| [Change requests](docs/change-requests.md) | The lifecycle, and what survives a branch deletion. |
+| [Reviews](docs/reviews.md) | Submitting reviews and commenting on individual changes. |
+| [Pre-merge checks](docs/checks.md) | What checks are and which ship built in. |
+| [Writing your own checks](docs/custom-checks.md) | The registry, an AI reviewer, and reporting from CI. |
+| [Event rules](docs/event-rules.md) | Firing a webhook or a script on a change request. |
+| [Merging, windows and auto-merge](docs/merging.md) | Change windows and automatic merging. |
+| [Protecting main](docs/protect-main.md) | Requiring a branch, optionally for part of NetBox only. |
+| [Automatic behaviours](docs/automation.md) | Stale reviews, reevaluation, notifications. |
+| [Administration guide](docs/admin-guide.md) | Roles, the permission matrix, building policies, troubleshooting. |
+| [Permissions](docs/permissions.md) | The short reference for every permission name. |
+| [REST API](docs/api.md) | Every endpoint. |
+| [Extending this plugin](docs/extending.md) | How another plugin adds content and checks. |
+| [Design](docs/design.md) | Why it is built this way. |
+
+## Features
+
+| 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 |
+
+## Requirements
+
+| Component | Version |
+|---|---|
+| NetBox | `>= 4.6.9, < 4.7` |
+| netbox-branching | `>= 1.1.3, < 1.2` |
+| Python | `>= 3.12` |
+
+## Quick install
+
+```python
+# configuration/plugins.py
+PLUGINS = [
+    'netbox_change_control',
+    'netbox_branching',          # must stay last
+]
+
+PLUGINS_CONFIG = {
+    'netbox_branching': {
+        'exempt_models': ['netbox_change_control.*'],   # required
+    },
+}
+```
+
+```bash
+./manage.py migrate netbox_change_control
+```
+
+See [Installation and configuration](docs/installation.md) for the detail, including why `exempt_models` is not optional.

netbox_change_control-0.3.0/netbox_change_control/__init__.py

@@ -0,0 +1,87 @@
+from netbox.plugins import PluginConfig, get_plugin_config
+
+__version__ = '0.3.0'
+
+
+class ChangeControlConfig(PluginConfig):
+    name = 'netbox_change_control'
+    verbose_name = 'NetBox Change Control'
+    description = 'Policy-driven change control and mandatory review for NetBox branches'
+    version = __version__
+    base_url = 'change-control'
+    # NetBox refuses to load the plugin outside this range, which is the only place the
+    # requirement is enforced rather than documented. The floor is 4.6.9 because that is what
+    # is tested; below 4.6.5 the initial migration cannot even apply, since it depends on
+    # extras.0140, and below 4.6.0 on core.0024 and users.0016 as well.
+    min_version = '4.6.9'
+    max_version = '4.6.99'
+    default_settings = {  # noqa: RUF012
+        # Block writes to branching-supported models outside of a branch. Users holding the
+        # netbox_change_control.bypass_policy permission are exempt.
+        'protect_main': False,
+        # Limit protect_main to specific models. Empty means every branching-supported model.
+        # Entries are 'app_label.modelname' or 'app_label.*', for example ['circuits.*'].
+        'protect_main_scope': [],
+        # Refuse to merge a branch which has no approved change request. This is the core
+        # guarantee of the plugin; disable it only to troubleshoot.
+        'enforce_merge_gate': True,
+        # Send a NetBox notification to the outstanding reviewers when a change request
+        # needs review, and to the requester when it is approved or rejected.
+        'notify_reviewers': True,
+        # Where a branch page shows its change request. 'right_page' puts it in a card in
+        # the right-hand column, beside branching's own cards; 'alerts' puts it in a band
+        # across the top of the page, above them. Naming both shows both, and an empty list
+        # shows neither.
+        'branch_page_placement': ['right_page'],
+        # Which built-in pre-merge checks to make available. True offers all of them, False
+        # none, and a list a subset. Registering only makes a check selectable: a policy
+        # decides where it applies, by naming it in its Checks field. Valid names:
+        #   'has-changes'       the branch contains something to merge
+        #   'no-conflicts'      no conflicts with main
+        #   'not-stale'         the branch is recent enough to sync
+        #   'threads-resolved'  every comment thread on the Changes tab is resolved
+        'enable_builtin_checks': True,
+        # Checks reported by an external system through the REST API. Each is created as
+        # pending and blocks the merge until a result is reported. Entries are a name, or a
+        # (name, label) pair.
+        'required_external_checks': [],
+        # Allow change requests to merge themselves once every gate is satisfied. Each
+        # request must also opt in individually. Turning this off disables the feature
+        # globally without editing any request, and stops the periodic job being registered.
+        'enable_auto_merge': True,
+        # Minutes between automatic merge sweeps. This bounds how late a change window can
+        # fire: at 10, a window opening at 21:00 merges by 21:09. Lower it for tighter
+        # windows, at the cost of one Job record per run. A change window shorter than this
+        # interval may never merge automatically, and says so on the change request. Takes
+        # effect when the worker restarts.
+        'auto_merge_interval': 10,
+    }
+
+    def ready(self):
+        super().ready()
+
+        from netbox_branching.models import Branch
+
+        # NetBox auto-imports a plugin's navigation, search and template_content modules, but
+        # not its dashboard module, so a widget is registered only if something imports it.
+        # Without this the My Reviews widget is missing from "Add widget", and a dashboard
+        # already holding one fails to load at all.
+        from . import dashboard, events, signal_receivers  # noqa: F401
+
+        # Registering the job is what makes rqworker schedule it, so skipping the import
+        # when auto-merge is off means no periodic job and no Job records at all.
+        if get_plugin_config('netbox_change_control', 'enable_auto_merge'):
+            from . import jobs  # noqa: F401
+        from .checks import register_builtin_checks
+        from .validators import require_approved_change_request
+
+        Branch.register_preaction_check(require_approved_change_request, 'merge')
+
+        # Registering makes a check available; a policy decides where it applies. True makes
+        # every built-in available, False none, and a list a subset.
+        selection = get_plugin_config('netbox_change_control', 'enable_builtin_checks')
+        if selection:
+            register_builtin_checks(list(selection) if isinstance(selection, (list, tuple, set)) else None)
+
+
+config = ChangeControlConfig

netbox_change_control-0.3.0/netbox_change_control/api/serializers.py

@@ -0,0 +1,251 @@
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
+
+from netbox_change_control.models import (
+    ChangeComment,
+    ChangeRequest,
+    MergeCheck,
+    Policy,
+    PolicyRule,
+    Review,
+)
+
+__all__ = (
+    'ChangeCommentSerializer',
+    'ChangeRequestSerializer',
+    'MergeCheckSerializer',
+    'PolicyRuleSerializer',
+    'PolicySerializer',
+    'ReviewSerializer',
+)
+
+
+class PolicySerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:policy-detail')
+
+    class Meta:
+        model = Policy
+        fields = (
+            'id',
+            'url',
+            'display',
+            'name',
+            'description',
+            'enabled',
+            'weight',
+            'object_types',
+            'conditions',
+            'condition_state',
+            'checks',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name')
+
+
+class PolicyRuleSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:policyrule-detail')
+    policy = PolicySerializer(nested=True)
+
+    class Meta:
+        model = PolicyRule
+        fields = (
+            'id',
+            'url',
+            'display',
+            'policy',
+            'name',
+            'min_reviews',
+            'groups',
+            'users',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'min_reviews')
+
+
+class ChangeRequestSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:changerequest-detail')
+    approved = serializers.BooleanField(source='is_approved', read_only=True)
+    branch_name = serializers.CharField(read_only=True)
+    branch_deleted = serializers.BooleanField(read_only=True)
+    ready_to_merge = serializers.BooleanField(source='is_ready_to_merge', read_only=True)
+    # Derived from the policy evaluation, so it is reported and never set. A writable status
+    # let a caller mark a request Completed, which is terminal and blocks its branch from ever
+    # merging. Use the abandon and reopen actions for the two transitions a person makes.
+    status = serializers.CharField(read_only=True)
+    merge_blocked_reason = serializers.CharField(read_only=True)
+    has_conflicts = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = ChangeRequest
+        fields = (
+            'id',
+            'url',
+            'display',
+            'ref',
+            'branch',
+            'branch_name',
+            'branch_deleted',
+            'title',
+            'description',
+            'status',
+            'priority',
+            'requester',
+            'approved',
+            'ready_to_merge',
+            'merge_blocked_reason',
+            'has_conflicts',
+            'scheduled_start',
+            'scheduled_end',
+            'auto_merge',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'ref', 'title', 'status')
+
+
+class ReviewSerializer(NetBoxModelSerializer):
+    """
+    A review is a personal statement, so the API records it as the caller and never as
+    somebody else.
+
+    `reviewer` is read-only and defaults to the requesting user. Leaving it writable let any
+    token holding `add_review` post an approval attributed to a colleague, which defeats the
+    merge gate with one request. The object form does not offer the field for the same reason.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:review-detail')
+    reviewer = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    class Meta:
+        model = Review
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'reviewer',
+            'decision',
+            'comment',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'decision')
+
+    def validate(self, attrs):
+        """
+        Attribute a new review to the caller.
+
+        A read-only field carrying a default is not enough, because DRF leaves a read-only
+        field out of validated_data entirely. The assignment also has to happen before
+        super(), since NetBox's ValidatedModelSerializer builds a model instance from these
+        attributes and calls full_clean() on it, which would reject the missing reviewer.
+        """
+        # `not self.nested` matters: a nested serializer's to_internal_value returns a model
+        # instance rather than a dict, and assigning into it raises TypeError.
+        if self.instance is None and not self.nested:
+            request = self.context.get('request')
+            if request is not None:
+                attrs['reviewer'] = request.user
+        return super().validate(attrs)
+
+
+class MergeCheckSerializer(NetBoxModelSerializer):
+    """
+    External systems report a result by PATCHing status, summary and details_url onto an
+    existing check.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:mergecheck-detail')
+    blocks_merge = serializers.BooleanField(read_only=True)
+    # A reporter must not decide whether its own check counts. Requiredness comes from the
+    # configuration or the policy, and the gate reads it from there rather than from this row,
+    # so a writable field here would only mislead.
+    required = serializers.BooleanField(read_only=True)
+    # The check belongs to the change request which created it. Moving it elsewhere would
+    # detach a result from what it was measuring.
+    change_request = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    class Meta:
+        model = MergeCheck
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'name',
+            'label',
+            'status',
+            'required',
+            'summary',
+            'details_url',
+            'completed',
+            'blocks_merge',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'status')
+
+
+class ChangeCommentSerializer(NetBoxModelSerializer):
+    """
+    A comment is a personal statement, so the API records it as the caller and never as
+    somebody else.
+
+    `author` is read-only and defaults to the requesting user, for the same reason `reviewer`
+    is on ReviewSerializer. Leaving it writable let any token holding `add_changecomment` post
+    a comment attributed to a colleague, which is enough to fake a sign-off in the discussion
+    a reviewer reads before approving.
+    """
+
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_change_control-api:changecomment-detail')
+    author = serializers.PrimaryKeyRelatedField(read_only=True)
+
+    def validate(self, attrs):
+        """
+        Attribute a new comment to the caller.
+
+        A read-only field carrying a default is not enough, because DRF leaves a read-only
+        field out of validated_data entirely. The assignment also has to happen before
+        super(), since NetBox's ValidatedModelSerializer builds a model instance from these
+        attributes and calls full_clean() on it, which would reject the missing author.
+        """
+        # `not self.nested` matters: a nested serializer's to_internal_value returns a model
+        # instance rather than a dict, and assigning into it raises TypeError.
+        if self.instance is None and not self.nested:
+            request = self.context.get('request')
+            if request is not None:
+                attrs['author'] = request.user
+        return super().validate(attrs)
+
+    class Meta:
+        model = ChangeComment
+        fields = (
+            'id',
+            'url',
+            'display',
+            'change_request',
+            'change_diff',
+            'parent',
+            'author',
+            'text',
+            'resolved',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'text')