NetBox Branching

To perform operations on NetBox objects within the context of a specific branch, you must include the X-NetBox-Branch HTTP header in every request. This header must contain the branch's schema ID (a pseudorandom eight-character alphanumeric identifier).

Important Notes:

• The value in the header does not include the branch_ prefix used in the underlying database.
• The header is only required when making changes to NetBox objects (like sites, prefixes, etc.) within a branch context. It is not required when managing the branches themselves.
• To 'deactivate' a branch for subsequent requests, simply omit the header.

# Example: Retrieve all site objects within a specific branch context
curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
-H "X-NetBox-Branch: td5smq0f" \
http://netbox:8000/api/dcim/sites/

NetBox Branching uses NetBox's ObjectChange audit log to replay changes.

Automatic Support

Any model that inherits from ChangeLoggingMixin (directly or via base classes like NetBoxModel, PrimaryModel, OrganizationalModel, or NestedGroupModel) is automatically branchable. No extra code is needed.

Unsupported Models

• Models without ChangeLoggingMixin: These are excluded from branching. Changes made to them inside a branch are not isolated and affect the main schema immediately.
• Multi-table inheritance: Models using Django's multi-table inheritance are incompatible. Each model in a branch must map to a single, self-contained table.

Best Practices for Model Selection

Branching is intended for network inventory or topology (e.g., devices, sites, prefixes). It is generally not appropriate for system-level or administrative state (e.g., user accounts, API tokens, permissions, or plugin configuration).

If a branch worker is killed abruptly (e.g., OOM kill, kill -9), the branch may be stuck in a transitional status (Provisioning, Syncing, Migrating, Merging, or Reverting).

When auto_recover_stuck_branches is True (default), an hourly background job resets these orphaned statuses to a safe state. It does not re-run the interrupted operation to avoid infinite crash loops.

Status Reset Mapping:

Manual Recovery: Users can manually recover branches via the Recover button in the UI or the /api/plugins/branching/branches/<id>/recover/ REST API endpoint.

• For Syncing or Migrating, you can opt to re-run the operation by passing {"retry": true} to the REST API or checking the Sync the branch / Apply the outstanding migrations checkbox on the Recover page.
• Warning: A branch interrupted during Provisioning is reset to Failed because its schema may be incomplete. You should delete and recreate such branches.

PLUGINS_CONFIG = {
    'netbox_branching': {
        'auto_recover_stuck_branches': False,
    }
}

NetBox provides two strategies for applying branch changes to main. Both read from the ObjectChange audit log, but differ in application logic.

Iterative (Default)

Replays every ObjectChange log entry from the branch into main in chronological order, one at a time.

• Pros: Preserves full granular audit trail in main (original user and timestamp attribution).
• Cons: Can fail if intermediate states violate constraints or if objects were modified/deleted in main during the branch lifecycle.

Squash

Collapses all changes made to each individual object in the branch into a single operation (the net effect) before applying it to main.

• Pros: Sidesteps intermediate state errors; handles foreign key dependencies automatically (deletes before creates); useful for recovering from duplicate object conflicts.
• Cons: main's changelog only shows the final state, attributed to the user who performed the merge, losing the granular history of the branch.

Understanding the core concepts of the branching model:

• Main: The primary NetBox state. Changes made outside of a specific branch context occur here.
• Change: The creation, modification, or deletion of an object.
• Branch: An independent copy of the NetBox data model that diverges from Main at a specific point in time.
• Provisioning: The automatic process of creating a dedicated PostgreSQL schema for a new branch.
• Synchronization: The process of pulling changes from Main into a specific branch to keep it up to date. Branches must be synchronized individually.
• Migration: The process of applying database migrations to a branch schema, required after NetBox upgrades.
• Merge: Incorporating changes from a branch back into Main.
• Revert: Undoing a merge by replaying the changes in reverse order (available if the branch hasn't been archived or deleted).
• Archive: Deprovisioning a branch's PostgreSQL schema while retaining its metadata. Archived branches cannot be reverted.