Add NetBox Branching support

[mrmrcoleman]

Imagine a scenario in which we're extracting information from a 3rd party system to be written to NetBox. In NetBox instances that have many users and downstream systems, overwriting information directly in main can interfere with other people's work.

NetBox Branching allows users to conduct their work in branches that are separate from the main NetBox data model and can be diff'd, merged, sync'd etc. With branching the information extracted from the 3rd party system can be written to a branch where it can be inspected in isolation before being merged into main.

Docs: https://docs.netboxlabs.com/netbox-extensions/branching/
Repo: https://github.com/netboxlabs/netbox-branching

---

Ideally it should be possible to specify a branch's schema_id when writing to NetBox so that any actions are applied to the branch and not main.

Applying changes to branches is currently supported in pynetbox by updating the nb.http_session.headers like this:

import pynetbox

nb = pynetbox.api(
    'http://localhost:8000/',
    token='92e786e2344c7f6eded06309a75d2deef595f2bc'
)

num_sites = len(nb.dcim.sites.all())
print(f"number sites main branch: {num_sites}")

# switch to Branch 'a'
branch = nb.plugins.branching.branches.get(name='a')
nb.http_session.headers["X-NetBox-Branch"] = branch.schema_id

num_sites = len(nb.dcim.sites.all())
print(f"number sites a branch: {num_sites}")

This works great for one off jobs when you'll only be interacting with one branch during the execution. For jobs that might need to write to multiple branches, the risk with the above approach is that you forget to set the branch back to its previous state and end up writing to the wrong branch. In that scenario I've been using this sort of thing instead:

import contextlib
import pynetbox

nb = pynetbox.api(
    'http://localhost:8000/',
    token='92e786e2344c7f6eded06309a75d2deef595f2bc'
)

@contextlib.contextmanager
def use_branch(nb, branch_name):
    # Store current branch
    original_branch = nb.http_session.headers.get("X-NetBox-Branch", None)
    
    # Switch to new branch
    branch = nb.plugins.branching.branches.get(name=branch_name)
    nb.http_session.headers["X-NetBox-Branch"] = branch.schema_id
    
    try:
        yield
    finally:
        # Return to original branch or reset header
        if original_branch:
            nb.http_session.headers["X-NetBox-Branch"] = original_branch
        else:
            nb.http_session.headers.pop("X-NetBox-Branch", None)

# Usage example
print(f"number sites main branch: {len(nb.dcim.sites.all())}")

with use_branch(nb, 'a'):
    print(f"number sites in branch 'a': {len(nb.dcim.sites.all())}")

print(f"number sites main branch again: {len(nb.dcim.sites.all())}")

---

Additionally it would be useful to have a module specifically for interacting with branch objects themselves. Branches support the following actions:

• Create
• Delete
• Merge
• Sync
• Archive
• View

Create, Merge and Sync are all asynchronous, so would require some sort of polling mechanism to ensure successful completion.

---

Example workflow:

1. Use the branching module to create a new branch, wait for it to reach the "Ready" state, and store its schema_id
2. Use the schema_id to specify the branch that future creates, updates and deletes should be applied to
3. Apply creates, updates, deletes as normal
4. Merge the branch

[sc68cal]

I can see a lot of utility in this. One of the issues that I encountered at one $WORK with a (non-NetBox) DCIM system was the team that managed it worried about allowing access by outside teams, and allowing them to use the APIs to make changes to the DCIM system. This caused everyone to use spreadsheets as the interchange format when planning changes to the datacenter. There was a "staging" environment that trusted users could access but the bar for being trusted was very very high. I never bothered to try and get access to that staging environment, and as a result, work took more time and code had to be written to take data out of a NetBox instance where our proposed changes were made, and exported to a spreadsheet.

Having this branching concept would allow different parts of an organization to make changes in branches to the DCIM that can be "staged" for review and then eventually merged or rejected.

[mrmrcoleman]

Hey @sc68cal this is exactly the use case we see many orgs using NetBox Branching for.