Implement conflict handling in API

[edudppaz]

Plugin Version

0.7.1

Proposed functionality

Right now, the handling of conflicts on branches and the preventing of merge/sync is done directly via forms/views, so the API is not protected against this (a sync or merge dry-run gives no indication of any conflicts)

#3

This functionality should also be ported to the API, so, as shown on the GUI (via forms/views) if there is a conflict on the branch, it should at least give an error message as response on the job instead of just a completed with no errros.
Right now, the API does not mirror the GUI functionality when conflicts are present. This should be a fairly trivial implementation, by checking the conflicts table and bring back an error if the table has rows, just as is done on the form:

netbox-branching/netbox_branching/forms/misc.py

Line 13 in 0b89a58

class BranchActionForm(forms.Form):

Use case

Merging or Synching branches with conflicts via RestAPI

External dependencies

No response

[kuhball]

We just ran into the same issue. Trying to check for conflicts within a gitlab pipeline via api.

[jeremystretch]

@edudppaz could you elaborate on the specific change you're proposing please? For example, what would expect the API responses to look like in specific conditions?

[kuhball]

Since there hasn't been any response from @edudppaz I'm trying to jump in.

Our scenario is the following:

1. Create two branches
2. Change an interface tagged vlan in one branch
3. Merge the branch
4. Change the same interface tagged vlan in the other branch

This results in a conflict in the UI.

We're relying on a config-generation tool which is triggered by webhooks and renders configuration into a git repository. This is also where we're running pytest to validate the configuration. Our approach was to add a pipeline which is executing a merge without commit via api in netbox. We were expecting the api to somehow represent the conflict which is shown in the ui.

Not knowing there is a conflict and changes have happened to the main branch in netbox could result in unwanted config overwrites for us.

[edudppaz]

Hi. Sorry i have been busy with work.

Thats almost exactly my use case, we are using a pipeline to deploy config via netbox branches and the plan was to run a dry-run before merging to verify there were no conflicts. But as of right now, a dry-run of a branch with conflict (via API) just says everything is OK and gives no indication of the conflicts, while the GUI gives a clear warning and needs acknowledgements.

Imho, the API on dry-run should at least give a warning that there are merge conflicts, or for api-only workflows (non gui) there is no way kf knowing the merge will overwrite newer data on main.

[jeremystretch]

@kuhball @edudppaz I understand the use case, but not the proposed implementation.

For example, what would expect the API responses to look like in specific conditions?

[kuhball]

I see 2 potential implementations.

1. Add the information from the merge ui page to the api GET of a branch. This would be my preferred way, feels pretty analog to the ui. The way how the conflict information is displayed is nothing final, pretty sure there is a smarter way.

{
    "id": 22,
    "url": "...",
    "display": "multiple-vlan-conflict",
    "name": "multiple-vlan-conflict",
    "status": {
        "value": "ready",
        "label": "Ready"
    },
    "owner": {
        "id": 2,
[...]
    },
    "description": "",
    "schema_id": "n4p4foj8",
    "last_sync": "2025-10-06T10:25:21.738020+02:00",
    "merged_time": null,
    "merged_by": null,
    "comments": "",
    "tags": [],
    "custom_fields": {},
    "created": "2025-10-06T10:25:17.573143+02:00",
    "last_updated": "2025-10-06T10:25:17.573154+02:00"
    "conflict": {
        "state": true,
        "conflicts": [
            "int a, origin xyz",
            "int b, origin xyz"
        ],
    }
}

2. Add the information to a merge operation without commit. This is a bit like clicking on merge in the ui and the attached screenshot is displayed. Executing merge via api with commit merges the branch and overwrites the data in the main branch.

{
    "id": 3244,
[...]
    "display": "Merge branch",
    "object_type": "netbox_branching.branch",
    "object_id": 21,
    "name": "Merge branch",
    "status": {
        "value": "conflict",
        "label": "Conflict"
    },
    "created": "2025-10-06T10:23:16.856996+02:00",
    "scheduled": null,
    "interval": null,
    "started": "2025-10-06T10:23:16.873480+02:00",
    "completed": "2025-10-06T10:23:17.355244+02:00",
    "user": {
[...]
    },
    "data": {
        "log": [
            "Merging branch merge-conflict (branch_3v5a9voo)",
            "Found 2 changes to merge",
            "Setting branch status to merging",
            "Applying change DCIM | interface GigabitEthernet1/0/3 updated by adm.couball using default",
            "Updating interface GigabitEthernet1/0/3",
            "Applying change DCIM | interface GigabitEthernet1/0/3 updated by adm.couball using default",
            "Updating interface GigabitEthernet1/0/3",
            "Dry run completed; rolling back changes"
        ],
        "conflict": [ list of found conflicts ]
    },
    "error": "conflict found",
    "job_id": "c7aadcbb-4d13-434e-ab64-360e09e30496",
    "log_entries": []
}