Skip to content

feat(netbox): add NetBox Branching support (branch_schema_id / branch_name / branch_id) - #639

Open
bragenr wants to merge 2 commits into
bb-Ricardo:developmentfrom
bragenr:feature/netbox-branch-header
Open

bragenr wants to merge 2 commits into
bb-Ricardo:developmentfrom
bragenr:feature/netbox-branch-header

Conversation

@bragenr

@bragenr bragenr commented Nov 20, 2026

Copy link
Copy Markdown

Summary

Adds support for the NetBox Branching plugin. When a branch is configured in the [netbox] section, every NetBox API request carries the X-NetBox-Branch: <schema_id> header, so all reads and writes are performed inside that branch. Branch selection via the REST API is stateless, which is why the header must be sent on every request.

Related feature request: #508

Changes

  • module/netbox/config.py: new optional [netbox] settings branch_schema_id, branch_name and branch_id. Mutually exclusive, rejected by config validation if more than one is set. Also available as env vars (NBS_NETBOX_BRANCH_SCHEMA_ID, NBS_NETBOX_BRANCH_NAME, NBS_NETBOX_BRANCH_ID).
  • module/netbox/connection.py: new NetBoxHandler.setup_branch_header() called right after the shared requests.Session is created. The X-NetBox-Branch header only accepts the branch's 8-char schema ID (verified against the plugin source), so branch_name/branch_id are first resolved to the schema ID via /api/plugins/branching/branches/ on the main schema, before any branch header is set. Clear fatal errors for 404 (plugin not installed), 403 (token permission), unknown branch names. The header is set once on the shared session, so it covers all queries, creates, updates and prune/delete. When a branch is active, caching is auto-disabled with a warning (main-schema cache must not mix with branch data).
  • settings-example.ini: regenerated with python3 netbox-sync.py -g (only the new documented options added).
  • tests/test_netbox_branch_header.py: 10 new tests — header behavior, name/ID resolution, error paths, caching switch-off, config validation.

Configuration

[netbox]
; exactly one of the three:
branch_schema_id = td5smq0f
;branch_name = my-feature-branch
;branch_id = 7

Verification

  • python -m pytest: 247 passed, 46 skipped (skips are vcsim integration tests; vcsim not installed here)
  • Smoke-tested config parsing from INI and env vars, including mutual-exclusion validation
  • Tested by me against a demo NetBox instance with netbox-branching: dry-run (-n -l DEBUG2) shows the NetBox Branching enabled... log line, then a real sync into a disposable branch

Notes for reviewers

  • Orphan/prune decisions inside a branch are made against the branch snapshot; prune_enabled = false recommended for initial branch tests.
  • branch_name/branch_id require the netbox-branching plugin and a token with read permission on branching branches.
  • No source-handler changes needed; fully centralized in the NetBox session setup.

Copilot AI balanced review requested due to automatic review settings November 20, 2026 11:06

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

mistral-vibe and others added 2 commits November 20, 2026 11:20
Send the 'X-NetBox-Branch: <schema_id>' header on every NetBox API
request when 'branch_schema_id' is set in the [netbox] section, so all
reads and writes target the given branch. The header is set once on the
shared requests.Session in NetBoxHandler.create_session(). Also
available via the NBS_NETBOX_BRANCH_SCHEMA_ID environment variable.

Co-authored-by: bragenr <bragenr@users.noreply.github.com>
The X-NetBox-Branch header only accepts the branch schema ID, so
branch_name and branch_id are resolved to the schema ID via the
branching plugin API (/api/plugins/branching/branches/) at startup,
before the header is set. The three options are mutually exclusive
and validated in the config. Caching is disabled automatically when a
branch is used, since main-schema cache data must not be mixed with
branch data.

Co-authored-by: bragenr <bragenr@users.noreply.github.com>
@bragenr
bragenr changed the base branch from main to development November 20, 2026 11:26
@bragenr
bragenr force-pushed the feature/netbox-branch-header branch from 9902e62 to 21f6604 Compare November 20, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants