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, until the branch ends. Nothing in NetBox tells Designs when that happens, so Designs asks whenever you open the Deployments page or use the branch, and acts on what it finds:

• Merged: the deployment moves to main, with everything it owns and its history: the plans that built it are listed under it on main. NetBox gives merged objects the ids they had on the branch, so the deployment goes on owning what it created, and Redeploy, Check drift and Tear down work on main from then on. If main already has an active deployment of the same name and design, the branch's is released instead: its objects are on main, owned by nothing, until a plan of main's adopts them. The plan into the branch says so when it starts such a deployment, while the name can still be changed; afterwards the released deployment's panel says why it was released, names what it left on main, and offers to deploy the same design on main with its variables, which plans as adoptions.
• Deleted: its objects went with the branch. The deployment is listed as Branch gone, out of use and owning nothing, and Remove forgets it. A plan into a branch of the same name makes a new, empty branch.

A plan aimed at a branch that has ended says so rather than planning against a branch that isn't there. So does applying one: a plan made into a branch that was merged or deleted before you pressed Apply is refused, naming the branch and offering Plan again, instead of being written into a branch NetBox no longer has.

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.