Plan into a branch

A plan can target a NetBox branch instead of the main schema. Applying it writes to the branch, so you can review the result in NetBox before anything reaches main. The NetBox needs the NetBox Branching plugin, and the token's user needs its permissions to create and use branches. The tutorial's Deploy into a branch does this with the compute rack.

1. On the deploy page, enter a name under Branch, such as riga-dc-build. Designs creates the branch if NetBox doesn't have it.
2. Choose the deployment and variables as usual, and select Plan. The plan is computed against the branch.
3. Apply the plan. The changes are in the branch, and main is unchanged.
4. In NetBox, review the branch, and merge it when you're ready, or delete it to throw the changes away.

A NetBox branch is another NetBox as far as deployments are concerned: a deployment planned into riga-dc-build is that branch's, separate from deployments on main. After a merge, plan the same design against main as a new deployment: it adopts what the merge brought in rather than creating it again. An adopted object is never deleted by the deployment that adopted it, so a deployment that should be able to tear its objects down later is better deployed to main directly, once the branch has shown you what it builds.

A write NetBox rejects on a branch

On NetBox 4.7.0 to 4.7.2, a write into a branch that NetBox rejects (a field it requires left out, a value it won't take) is answered with a server error, "The rollback flag doesn't work outside of an 'atomic' block", in place of the field error it would give on main. This is netbox-community/netbox#23366, fixed in NetBox after 4.7.2. Designs writes objects of one type together; when NetBox answers this way, Designs writes them again one at a time, so the apply's errors name the object and the field NetBox refused, and the objects that were valid are written. The adapter log records NetBox's answer, and at debug level the payload it refused.