End-User Guide

This guide is for the two roles that take part in day-to-day change management: requesters, who stage changes in a branch and ask for review, and reviewers, who evaluate those changes and decide whether they can be merged. It assumes an administrator has already configured at least one change policy; if that hasn't been done yet, see the Administration Guide.

The Introduction walks through the workflow end to end at a high level. This guide goes deeper on the change request lifecycle and the specific tasks each role performs.

Core Concepts

Change Requests and Branches

A change request is always tied to a single branch. The branch is where you stage your work; the change request is the formal proposal to review and merge it. The "changes being reviewed" are simply the object creations, edits, and deletions recorded in that branch, viewable on the change request's Changes tab.

A branch can have only one active change request at a time. Once a change request reaches a terminal state (Completed or Rejected), it no longer blocks the branch, but in normal use each branch moves through a single change request from start to merge.

See ChangeRequest for the full data model.

Policies and Rules

A change policy decides who may approve a change request and how many approvals it needs. Each policy is made up of one or more rules, and a change request is approved only when every enabled rule in its policy is satisfied. A rule is satisfied when it collects at least its required number of approvals (Minimum reviews) from eligible reviewers.

Administrators define policies and rules; as a requester or reviewer you mostly need to know which policy applies to a given change request and what it requires. For the policy concept with a worked example, see Defining a Policy; for authoring rules, see Configuring Policies.

Being able to submit a review is not the same as being eligible to satisfy a rule. Anyone with permission to add reviews can review any change request, but only reviews from eligible reviewers count toward policy compliance. Eligibility is set by each rule's Reviewer Groups and Reviewers fields: you are eligible for a rule if you belong to one of its reviewer groups or are named individually as a reviewer. A review from an ineligible user is recorded and visible, but does not move the change request toward approval. The Administration Guide is the canonical reference for permissions and eligibility.

Change Request States

A change request moves through six states:

Only Draft and Needs review can be chosen when a change request is first created. A Completed change request follows a merge and is the end of the workflow. A Rejected change request is declined, but isn't permanent: someone can re-open it by moving it back to an active status (Draft, Needs review, or Changes requested), as long as its branch has no other active change request. See ChangeRequest for status details.

Lifecycle and Status Transitions

Some transitions are made by people (a requester opening a request for review, a reviewer requesting changes); others happen automatically as a result of reviews, branch activity, or a merge. The Automatic Behaviors section of the Introduction summarizes the automatic side; the table below shows who or what drives each move.

How a Change Request Moves Between States

A change request is never approved manually: it becomes Approved only when the policy's rules are all met, and it returns to Needs review automatically if later activity invalidates that. A review of Changes requested moves the request to Changes requested no matter who submits it, but only approvals from eligible reviewers count toward the policy. Rejecting is always a manual status change; a review of Rejected is recorded as feedback but does not decline the request on its own.

Stale Reviews

When new changes are made to a branch after a review was submitted, that review becomes stale: it no longer reflects the current state of the branch, so its approval stops counting toward the policy. This is why an Approved change request reverts to Needs review when its branch changes again, and why reviewers may need to take another look. See Review for how staleness is tracked.

For Requesters

This section expands on Create a Change Request.

Creating a Change Request

When you've finished staging your changes in a branch, click the request review button at the top of the branch view to open the change request form. Enter a name (or keep the default taken from the branch name), select the change policy that applies, set a priority, and provide a brief summary for reviewers. A new change request opens in Draft status by default; you can also open it directly in Needs review if it's ready. These are the only two statuses available at creation.

Submitting for Review

If you created the change request as a Draft, change its status to Needs review when it's ready. This opens it for review and begins collecting the approvals its policy requires.

Responding to Reviewer Feedback

Reviewers leave feedback in two places: as reviews listed on the change request, and as comments on specific changes in the Changes tab. You can reply to a comment to continue the discussion, and a comment can be marked resolved once it's been dealt with. Resolving a comment is a tracking aid only; it does not affect whether the change request can be approved.

After you've made the requested changes in the branch, set the status from Changes requested back to Needs review to ask reviewers to take another look. See Comment and CommentReply for details.

What Happens After Approval

Once the policy is satisfied, the change request moves to Approved and a merge button appears (see Applying a Change Request). Merging the branch automatically sets the change request to Completed.

A couple of things to keep in mind:

• A branch cannot be merged without an approved change request. This pre-merge gate applies regardless of the protect_main setting.
• If you push more changes to the branch after approval, the change request reverts to Needs review and must be re-approved before it can be merged.

For Reviewers

This section expands on Reviewing a Change Request.

Finding Change Requests That Need Review

Navigate to Plugins > Change Management > Change Requests and filter the list by Status: Needs review to see the change requests awaiting approval. A change request shows its policy, so you can see which rules apply and how many approvals are still outstanding.

Understanding What You're Reviewing

Open the change request and select the Changes tab to see the work staged in its branch: the objects created, edited, or deleted, shown as a diff against the current state of NetBox. This is what your review applies to. See the netbox-branching documentation for more on how branches capture changes.

Submitting a Review

Click the add a review link above the list of reviews, choose a status, and add any comments. The review statuses are:

For more detailed, line-level feedback, use the Changes tab to comment on specific changes within the branch; the requester and other users can reply to those comments. See Review and Comment.

Re-Reviewing After Changes

When a branch changes after you've reviewed it, your earlier review goes stale and its approval no longer counts. Submit a new review to reflect the updated branch. Only your latest review counts, so the normal flow of requesting changes and then approving once they're made works as expected.

Understanding Policy Requirements

A change request is approved only when every enabled rule in its policy is satisfied, and each rule needs its Minimum reviews count of approvals from eligible reviewers. Remember that being able to submit a review is not the same as being eligible to satisfy a rule (see Policies and Rules). For how rules are configured, see Configuring Policies and PolicyRule.