# Infrahub branching deep dive: inside the graph, the costs, and the limits

A source of truth is critical infrastructure. Automation reads it all day, so a wrong value in it becomes a wrong configuration on a device. Without branches, every edit lands live: a half-done migration, a maintenance plan and a test all share the database that production automation reads. [Infrahub](<https://github.com/opsmill/infrahub>) has native, Git-like branches for this data. I opened its graph and measured each step of a branch's life to see what "Git-like" really means.

A migration or a maintenance change should be a change that you prepare, review and check before it reaches the data, not a set of manual edits. I have worked a lot with [NetBox](<https://github.com/netbox-community/netbox>), and this is the part we always had to build around it. In the past we made it work with Git: the change lived in a repository, a merge request carried the review, and a pipeline wrote the result into NetBox. Then came [NetBox Branching](<https://github.com/netboxlabs/netbox-branching>), the extension that adds branches to NetBox, and I wrote a plugin on top of it, [netbox-change-control](<https://github.com/antoinekh/netbox-change-control>), for policy-driven change control and mandatory review. Both ways work, but neither is always simple.

Infrahub answers this need, and elegantly. Branches are native: you branch, you change the configuration, you open a proposed change, checks run, a reviewer approves, you merge. A custom check can block a change that breaks a rule, like CI on a GitLab merge request. But a source of truth is a database, not a Git repository, so "Git-like" hides real engineering choices. I wanted to understand them before trusting them, and to gate a real maintenance change with a check. A second post uses the same lab to trace service dependencies: [Which services sit behind this router?](<https://blog.antoinekh.dev/posts/infrahub-graph-traversal/index.md>)

> [!NOTE]
>
> **Changelog**
>
> - **2026-11-04:** I added the section [Bugs found along the way](<#bugs-found-along-the-way>).
> - **2026-10-30:** I added the section [Rollback: what if I messed up?](<#rollback-what-if-i-messed-up>).

> [!NOTE]
>
> **Tested on Infrahub 1.11.9**
>
> All tests in this post ran in October 2026 on Infrahub 1.11.9, the current release at the time of writing: Community edition, release compose file, Neo4j 2026.05.0 Community, 4 API workers and 2 task workers.

## TL;DR

- **A branch is a filter, not a copy.** Values hang on edges tagged with a branch and a time range; creating a branch writes one node and one relationship. Nothing is overwritten, and nothing is trimmed.
- **Creating and reading a branch are cheap.** About half a second of work to create, whatever the data size, and reads cost the same as on `main`.
- **The cost is in the life of the branch.** 16 to 43 s per merge and 16 to 28 s per delete.
- **The Git words do not mean the Git things.** No commits, one level of branches, "latest value wins" merges, and a rebase that moves a timestamp.
- **Rollback is a change forward.** There is no revert: you rebuild the old state from the history on a new branch, review it and merge it.
- **Custom checks work like CI on a merge request:** a Python check blocks any change that breaks one of your design rules, before it reaches `main`.
- **The free Community edition fits a lab or a network of up to about 1,000 devices.** For a large or critical network, enforced approvals and high availability need the Enterprise edition.

## The lab

All the tests and measurements ran on [a lab built for this post](<https://github.com/antoinekh/labs/tree/master/infrahub_branching>). It runs the Infrahub release compose file with the OpsMill demo data, plus a small BGP backbone schema of my own, `Net`: routers, interfaces, inter-site links, BGP sessions and application services. A script generates sites of 2 P routers, 4 PE routers and 1 route reflector (RR), for two graph sizes: 49k nodes (small) and 151k nodes (large). The lab README has the full details: containers, schema, data steps, scripts and raw results.

## How a branch is stored

Before the numbers, the model, because it explains all of them.

### A graph database in one minute

If you have only used relational databases, here is the vocabulary. Neo4j is a property graph database. It stores **nodes** (also called vertices), which carry one or more **labels** and a set of key-value **properties**, and **relationships** (edges), which always have one **type** and one direction, and can carry properties too. There are no tables and no foreign keys: a relationship is a record that points directly at its two nodes, so following it is a pointer hop, not a join through an index. Queries are written in Cypher, where you draw the pattern you look for: `(node)-[:TYPE]->(other)`.

This is the textbook way to model a network in a graph: one node per router, one edge per BGP peering, the attributes as properties. Infrahub does not store data like that, and the difference explains everything about its branches.

### Vertices and edges

Infrahub does not store an object as one Neo4j node with properties. It splits it into several vertices: one for the object, one per attribute, one per value, and a middle vertex for each relationship. And every edge carries the versioning: the branch that wrote it, when it became valid (`from`), when it stopped being valid (`to`), and a status. Here is the router `pe-par-01` as Infrahub stores it, with two of its attributes and one of its relationships:

> [!NOTE]
>
> **All vertex labels, edge types and edge properties**
>
> | Vertex | Role |
> | --- | --- |
> | `Root` | One vertex that anchors the graph |
> | `Branch` | One per branch, with its `name` and `branched_from` timestamp |
> | `Node` (also labelled with its kind, for example `NetDevice`) | The object, with its `uuid` |
> | `Attribute` | One per attribute of the object, for example `status` |
> | `AttributeValue` | The value itself, shared between all attributes that hold the same value |
> | `Relationship` | The middle vertex between two related objects |
> | `Boolean` | Flags such as `is_protected` |
>
> The edges carry the links: `IS_PART_OF` (object to root), `HAS_ATTRIBUTE` (object to attribute), `HAS_VALUE` (attribute to value), `IS_RELATED` (object to relationship to object), plus metadata edges such as `IS_PROTECTED`, `HAS_SOURCE` and `HAS_OWNER`. Every edge carries these properties:
>
> | Edge property | Meaning |
> | --- | --- |
> | `branch` | The branch that wrote the edge |
> | `branch_level` | 1 for `main` and the global branch, 2 for a user branch |
> | `from` | When the edge became valid |
> | `to` | When it stopped being valid, empty while it is current |
> | `status` | `active` or `deleted` |
> | `from_user_id`, `to_user_id` | Who opened and who closed it |

Values are de-duplicated: in the demo data, 27,019 attributes point to only 3,455 distinct `AttributeValue` vertices. Attributes that hold the same value, with the same flags, share one vertex.

### How a branch reads

A node does not belong to a branch. An edge does, for a time range. A query on a branch keeps an edge when:

- it is on `main` (or the global branch) and was valid at the branch's `branched_from` time, or
- it is on the branch itself and is valid now,

and when several edges compete for the same link, the one with the highest `branch_level` wins, then the most recent `from`, then `active` before `deleted`.

So when I set the status of `p-bdx-01` to `maintenance` on a branch, Infrahub does not copy the router. It adds one `HAS_VALUE` edge, tagged with the branch name, from the existing `status` attribute to the existing `maintenance` value. The `main` edge stays untouched. A query on `main` sees `active`; a query on the branch sees both edges and the branch edge wins.

As in Git, **a branch does not see changes made on `main` after it started.** It reads `main` frozen at `branched_from`, a timestamp on the `Branch` vertex, so queries, generators and checks on the branch all read that old `main`. Infrahub does not tell you that `main` moved; you rebase to catch up, which moves `branched_from` to the rebase time. I show it below.

You can see all this in Neo4j directly. Infrahub never needs you there, and you must never write there, but reading is the best way to understand the model:

```cypher
MATCH (d:NetDevice)-[:HAS_ATTRIBUTE {branch: 'main'}]->(:Attribute {name: 'name'})
      -[:HAS_VALUE {branch: 'main'}]->(:AttributeValue {value: 'p-bdx-01'})
MATCH (d)-[:HAS_ATTRIBUTE]->(a:Attribute {name: 'status'})-[r:HAS_VALUE]->(v)
RETURN r.branch, v.value, r.from, r.to
```

```text
"large-0", "maintenance", "2026-10-27T18:15:22.144336Z", NULL
"main",    "active",      "2026-10-27T18:04:02.243993Z", NULL
```

[![Neo4j Browser: one status attribute, two HAS\_VALUE edges, one per branch](<https://blog.antoinekh.dev/assets/images/infrahub-branching/neo4j-branch-value.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/neo4j-branch-value.png>)

### History and time travel

Nothing is overwritten. When a value changes on `main`, the old edge gets a `to` timestamp and a new edge starts. The graph keeps the full history, and any query accepts a point in time. Here is `rr-lys-01` on `main` at three moments of this lab, with `?at=` on the GraphQL endpoint:

```text
at=2026-10-27T18:30:00Z  status=active
at=2026-10-27T18:45:00Z  status=down
at=now                   status=maintenance
```

That is a real strength for operations: "what did the source of truth say during last night's incident?" is one query.

The other side: nothing trims the history of `main`. Version 1.11.9 has no retention setting and no command to drop the versions older than N days, so every change stays in the graph. Only branch history can go: deleting a branch removes its edges and their history for good, and a rebase drops the older history of the branch changes. The two cleanup commands do not touch the data history: `infrahub db delete-diffs` removes stored diffs, and `infrahub tasks flush flow-runs --days-to-keep 30` removes old task runs from the Prefect database. Size the disk for the history that you will keep, not for the current data.

### Not all data is branched

A schema element has a branch support mode:

- **aware** (the default for your data): follows the model above.
- **agnostic**: stored once on the global branch and visible on every branch at once. Accounts, tokens and resource pool reservations work like this, so two branches cannot take the same IP address or the same number from a pool.
- **local**: stays on the branch where it was set and is never merged.

## Measurement 1: creating a branch

Infrahub runs its background jobs with [Prefect](<https://github.com/PrefectHQ/prefect>), an open-source Python workflow engine. An API call that creates, merges or rebases a branch does not do the work itself: it submits a Prefect flow, the Prefect server (the `task-manager` container) queues it and keeps its state, a `task-worker` container runs it, and the client waits for the result. So every branch operation has a queue time and a run time, and I measured both.

The branch creation flow checks that the name is free under a distributed lock, takes a local schema lock, copies the schema of `main` in memory, saves the `Branch` vertex, adds the branch to the registry, and sends an event. Then every API and worker process receives a "refresh registry" message on RabbitMQ and loads the new branch. I saw those messages in the logs of all six processes for each branch.

I created branches with the SDK (`client.branch.create(..., sync_with_git=False, wait_until_completion=True)`), counted nodes and relationships before and after each one, and read the queue time and the run time of each flow from the Prefect API.

| Graph | Branches | Client time, median / max | Flow queue, median / max | Flow run, median / max | Graph added per branch |
| --- | ---: | ---: | ---: | ---: | --- |
| 49k nodes | 25 | not recorded | 0.82 s / 2.2 s | 0.50 s / 1.4 s | 1 node, 1 relationship |
| 151k nodes | 25 | 2.2 s / 3.2 s | 0.86 s / 1.5 s | 0.53 s / 0.79 s | 1 node, 1 relationship |

What it says:

- **One node and one relationship, every time.** The new `Branch` vertex and its `IS_PART_OF` link to the root. No data is copied. On disk, 25 branches added 229 KB to a 165 MB store, and most of that is page allocation.
- **The size of the graph does not matter.** A median of 0.50 s against 0.53 s for three times more data. The difference between the flow time and the client time is the queue and the SDK polling for the result.

Memory was my other suspect, because every process keeps one schema per branch. It does not matter in practice:

| Container | 1 branch | 26 branches |
| --- | ---: | ---: |
| API server (4 workers) | 1.524 GiB | 1.530 GiB |
| Task worker 1 | 402.7 MiB | 408.8 MiB |
| Task worker 2 | 385.1 MiB | 392.5 MiB |
| Neo4j | 1.756 GiB | 1.757 GiB |

### Compared to NetBox Branching

[NetBox Branching](<https://github.com/netboxlabs/netbox-branching>) takes the opposite approach, because NetBox stores its data in PostgreSQL, a relational database. A new branch is a new PostgreSQL schema, and provisioning it copies every branch-aware table of `main` into it: in v1.2.0, `INSERT INTO branch.table SELECT * FROM main.table` for each table under one snapshot, then a rebuild of the constraints and indexes, then the triggers. That is almost all the network data. Users and other non-branching models stay in `main`, and the change log starts empty.

So a NetBox branch costs time and disk in proportion to the data: a large database means a long provisioning and a full second copy of the data for each open branch. The plugin documentation says it too: its `provision_workers` setting copies the tables and builds the indexes in parallel to cut "provisioning time on multi-GB databases". I did not measure it here. In return, a NetBox branch is a plain set of tables, so reads inside it cost nothing more, and archiving a merged branch drops its schema and gives the space back.

## Measurement 2: reading a branch

The read rules above add work to every query on a branch: more edges to consider, and an ordering to find the winner. I ran the same query, all 1,064 routers of the large graph with three attributes each, seven times on three branches:

| Branch | Median | Min | Max |
| --- | ---: | ---: | ---: |
| `main` | 1.06 s | 0.98 s | 2.60 s |
| fresh branch, no change | 1.11 s | 0.96 s | 3.14 s |
| branch with 1,000 of the 1,064 routers changed | 1.15 s | 0.98 s | 2.49 s |

The median moves by 4% on a fresh branch and 9% when almost every object differs, less than the spread between two runs on `main` (0.98 to 2.60 s). For a source of truth that automation reads all day, **reading a branch costs the same as reading `main`.**

## Measurement 3: editing, diff and merge

An empty branch is not the interesting case. The real question is what a branch with many changes costs. On the large graph, I created a branch, changed the `owner` of N application services, refreshed the diff (`DiffUpdate`), merged it (`BranchMerge`), and counted the graph after each step.

| Changes | Edit | Added by the edit | Diff | Added by the diff | Merge | Added by the merge |
| ---: | ---: | --- | ---: | --- | ---: | --- |
| 10 | 1.5 s | 10 edges | 13.3 s | 32 nodes, 31 edges | 22.3 s | 10 edges |
| 100 | 5.1 s | 100 edges | 8.8 s | 302 nodes, 301 edges | 16.3 s | 100 edges |
| 1,000 | 41.0 s | 1,000 edges | 10.6 s | 3,002 nodes, 3,001 edges | 43.0 s | 1,000 edges |

### The edit

One edge per changed attribute. The 2 extra nodes are the new values, for example `team-noc-1000`, shared by all the services that hold it. 1,000 edits took 41 s with an SDK batch at concurrency 2, which is the speed of the API mutations, not of the branch.

### The diff

A diff is not computed on the fly when you open a page. A flow computes it and stores it in the graph: one `DiffRoot` for the branch, a partner `DiffRoot` with the changes of `main` over the same time range (Infrahub compares the two to find conflicts), and per changed attribute one `DiffNode`, one `DiffAttribute` and one `DiffProperty`, which holds the old and the new value. That is the "3 nodes and 3 edges per change" in the table: **a stored diff weighs three times more than the change itself.**

Infrahub does not compute the diff at each change: a flow updates it when a proposed change runs its checks, when you press Refresh diff, before a merge or a rebase, and after another branch merges into `main`. Each update calculates only the time since the last one.

The time stayed around 10 s from 10 to 1,000 changes, so at this scale it is mostly fixed overhead.

The diff also stores the conflicts: under the `DiffProperty`, a `DiffConflict` vertex keeps both values and the side you chose. That is why the diff must exist before a merge. A branch without a diff costs nothing: my 50 open benchmark branches had no proposed change, so the refresh after each merge (`INFRAHUB_DIFF_UPDATE_AFTER_MERGE`) skipped them.

### The merge

A merge is the most guarded operation. The flow:

1. takes the global merge lock, so only one merge or rebase runs at a time on the whole instance;
2. blocks writes on the source branch and on `main` (a write gets `MERGE_IN_PROGRESS`, HTTP 423); other branches stay writable;
3. refreshes the diff and checks the conflicts and constraints again against the current `main`, because another branch may have merged since the review;
4. writes the final value of each change on `main`: "latest value wins", the history inside the branch does not travel;
5. closes the old `main` edges with a `to` timestamp, so `main` keeps its history;
6. marks the branch `MERGED`, read-only for good.

The table shows one new `main` edge per change, and a time that is mostly fixed: 10 changes took longer than 100.

> [!WARNING]
>
> **A crashed merge needs an operator**
>
> A merge is not one database transaction: if the worker dies in the middle, the branch goes to `MERGE_FAILED`, `main` stays write-blocked, and an administrator runs `infrahub recover merge` to revert every `main` write since the merge started. A crashed merge is an operator task, not a retry.

The branch keeps its own edges until you delete it: after the merge of `bulk-1000`, one service owner had three edges, the old and the new value on `main`, and the new value on the branch.

## Measurement 4: deleting a branch

Removing a branch is always more work than creating one, and Infrahub is no exception. I deleted 50 benchmark branches with the SDK:

| Branches | Time | Per branch |
| ---: | ---: | ---: |
| 25 (while I was using the UI) | 11 min 40 s | 28 s |
| 25 | 6 min 30 s | 16 s |

**A delete takes 16 to 28 s, against about 2 s for a create, even for an almost empty branch.** A create writes one vertex; a delete must find and remove every edge of the branch, clean the vertices that only the branch used, release branch-agnostic values that nothing reaches any more, and refresh every registry. The graph went back to exactly the counts before the branches, edges included. The store file did not shrink: Neo4j keeps the space and reuses it later.

If your automation creates a branch per change, plan for the delete side, or set `INFRAHUB_DELETE_BRANCH_AFTER_MERGE` and let Infrahub delete each branch after its merge.

## The Git-style actions in practice

The Git words map to Infrahub, but not one to one:

| Git | Infrahub | What is different |
| --- | --- | --- |
| `git branch` | Create branch | Always from `main`, no branch of a branch. "Sync with Git" also pushes it to the read-write repositories |
| commit | Any change | There are no commits. Each change is a timestamped edge; there is no message and no unit to revert |
| `git diff` | Data tab of a branch or proposed change | Computed by a flow and stored in the graph. Refresh it with the button or `DiffUpdate` |
| merge request | Proposed change | Diff, checks, comments, reviewers, approvals |
| `git rebase` | Rebase | Moves `branched_from` to now, with no replay. Only the latest value of each branch change survives |
| `git merge` | Merge | "Latest value wins". Global lock, `main` write-blocked during the merge, branch frozen after |
| merge conflict | Conflict | Per attribute or per relationship. You pick a side; there is no text merge |
| cherry-pick, revert | none | No partial merge, no revert of a merged change: you write the inverse change on a new branch, see [Rollback](<#rollback-what-if-i-messed-up>) |

### A branch and an edit

I created the branch `maint-rr-lys-01` from the branch selector and set the status of `rr-lys-01` to `maintenance`. The branch name is on every screen and in every form, so you always know where you write.

[![Creating the branch maint-rr-lys-01](<https://blog.antoinekh.dev/assets/images/infrahub-branching/branch-create.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/branch-create.png>)

[![Editing rr-lys-01 on the branch](<https://blog.antoinekh.dev/assets/images/infrahub-branching/edit-in-branch.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/edit-in-branch.png>)

The API confirms the isolation: `main` returned `active`, the branch returned `maintenance`.

### The proposed change and its diff

Then I opened a proposed change from the branch to `main`. Its Data tab shows the stored diff:

[![The diff of the proposed change: status, active on main, maintenance on the branch](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-data-diff.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-data-diff.png>)

### A conflict

While the proposed change was open, another operator set `rr-lys-01` to `down` directly on `main`. The diff in the page did not change by itself. After "Refresh diff", Infrahub showed the conflict on the attribute, with the history of `main` (`active` then `down`), the branch value, and a choice of side:

[![The conflict: active then down on main, maintenance on the branch](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-conflict.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-conflict.png>)

I kept the branch value. The choice is stored with the diff and applied at merge time. Not every conflict can be solved this way: if one side deleted an object and the other changed it, no choice of side works, and the merge stays blocked until the data agrees on both branches.

### Rebase

To see the rebase, I created a branch `rebase-demo`, then changed the owner of `svc-pe-par-01-1` on `main`. The branch kept returning the old owner: it reads `main` as of its `branched_from`. The Rebase button moved `branched_from` to now, and the branch returned the new owner.

[![Branch details with the Rebase, Merge and Validate actions](<https://blog.antoinekh.dev/assets/images/infrahub-branching/branch-rebase.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/branch-rebase.png>)

A rebase takes the same global lock as a merge, checks the conflicts and the constraints first, and refuses if a conflict needs a decision that a rebase cannot apply (it always keeps the branch side). So the right habit is the one from Git: rebase before you ask for a review, and again after another branch merges.

## CI on a branch: custom checks

The proposed change is the merge request of Infrahub, and its validators are the CI. Some are built in:

- **Data Integrity**: the conflicts, and whether each one has a decision.
- **Schema Integrity**: the schema constraints (uniqueness, required values) on the data the merge would produce.
- **Artifacts, Generators, Repository**: the configuration artifacts and generators defined in your repositories, run on the branch data.

And the **user checks**, which are yours. A check is a GraphQL query plus a Python class, stored in a Git repository that Infrahub imports. A global check runs once against the whole branch; a targeted check runs once for each object of a group, with that object's values as query variables. A failing check blocks the merge.

### The rule

On the branch `maint-rr-lys-01`, `rr-lys-01` goes into maintenance. In the lab, every PE has two iBGP sessions: one to its local RR and one to the RR of Paris (`rr-par-01`), or of Lyon (`rr-lys-01`) for the Paris PEs. The rule I want: no PE may drop below two active route reflectors.

The schema makes this rule checkable. There is one BGP session object per router, and the `peer` relationship links the two ends, so a PE session finds the route reflector session at the other end, and the device behind it.

### The check

The check lives in a Git repository with three files:

.infrahub.yml

```yaml
---
queries:
  - name: pe_route_reflectors
    file_path: queries/pe_route_reflectors.gql

check_definitions:
  - name: pe_route_reflector_redundancy
    class_name: RouteReflectorRedundancy
    file_path: checks/route_reflector_redundancy.py
```

queries/pe\_route\_reflectors.gql

```graphql
query pe_route_reflectors {
  NetDevice(role__value: "pe") {
    edges {
      node {
        name { value }
        bgp_sessions {
          edges {
            node {
              status { value }
              peer {
                node {
                  ... on NetBgpSession {
                    device { node { ... on NetDevice { name { value } status { value } } } }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

checks/route\_reflector\_redundancy.py

```python
from typing import Any

from infrahub_sdk.checks import InfrahubCheck

MIN_ROUTE_REFLECTORS = 2


class RouteReflectorRedundancy(InfrahubCheck):
    query = "pe_route_reflectors"

    def validate(self, data: dict[str, Any]) -> None:
        for edge in data["NetDevice"]["edges"]:
            pe = edge["node"]
            active = []
            for session in pe["bgp_sessions"]["edges"]:
                peer = session["node"]["peer"]["node"]
                if session["node"]["status"]["value"] != "established" or not peer:
                    continue
                rr = peer["device"]["node"]
                if rr["status"]["value"] == "active":
                    active.append(rr["name"]["value"])
            if len(active) < MIN_ROUTE_REFLECTORS:
                self.log_error(
                    message=f"{pe['name']['value']} keeps {len(active)} active route reflector(s): {', '.join(active) or 'none'}",
                    object_id=pe["name"]["value"],
                    object_type="NetDevice",
                )
```

The query reads every PE, its BGP sessions, and through `peer` the status of the router at the other end. A PE fails only if it drops below two active route reflectors, so the check measures the impact of the change, not only what it touches. You can run it locally with `infrahubctl check pe_route_reflector_redundancy --branch=<branch>` before you push it.

I added the repository in Integrations, Git Repositories, as a read-only repository. A read-only repository stays on one commit and imports its content: it does not follow new commits on its Git branch, and you set the new commit on the repository object, in the UI or the API, to import it. A read-write repository also gets a Git branch for every Infrahub branch created with "Sync with Git". Infrahub imported the check definition within a minute.

[![Adding the Git repository that holds the checks](<https://blog.antoinekh.dev/assets/images/infrahub-branching/repository-add.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/repository-add.png>)

### The gate

On the proposed change of `maint-rr-lys-01`, the check ran next to Data Integrity and Schema Integrity, took 34 s, and failed. It names the 8 PEs that peer with `rr-lys-01`:

[![The check fails: each PE keeps only rr-par-01](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-checks-failed.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-checks-failed.png>)

The Merge button stays clickable, but the merge flow refuses it:

[![Merge refused: Unable to merge proposed change containing failing checks](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-merge-refused.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-merge-refused.png>)

That is the behavior I want from CI. The fix belongs in the change itself: on the same branch, I gave each of the 8 PEs a temporary session to a third RR, `rr-mrs-01`. "Retry all" ran the check again: it passed, and the merge went through.

[![The user check passes after the backup sessions are added; Data Integrity still lists the resolved conflict](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-checks-passed.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-checks-passed.png>)

Data Integrity stays red: it still lists the status conflict of `rr-lys-01`, resolved earlier in favor of the branch. A conflict with a decision does not block the merge; only a conflict without one does.

[![The proposed change merged into main](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-merged.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/pc-merged.png>)

On `main`, `rr-lys-01` is now in maintenance (the branch side of the conflict won), the backup sessions to `rr-mrs-01` exist, the proposed change is `merged` and the branch `MERGED`.

### What about a GitLab pipeline?

Checks run inside Infrahub, on its task workers. If you want an existing GitLab CI in the loop, there are hooks, but I did not test them:

- **Webhooks** send events to an external URL. The useful ones here: `infrahub.branch.created`, `infrahub.branch.rebased`, `infrahub.branch.merged`, `infrahub.proposed_change.approved`, `infrahub.proposed_change.merged`, `infrahub.validator.started`, `infrahub.validator.passed`, `infrahub.validator.failed`, and the node events. A custom webhook passes the event through a transformation, so you can build the payload that the GitLab pipeline trigger API expects. Note that proposed change events are emitted on the default branch, whatever their source branch.
- **A check is Python.** It can call anything the worker can reach (a GitLab pipeline, a REST API, a lab) and fail with `log_error`. That is the way to make an external result gate the merge, since the pipeline result itself does not come back as a native validator.

## Rollback: what if I messed up?

A check stops only what a rule covers. Here is a change that no rule of my lab covers, and how to take it back once it is on `main`.

### The mistake

A cleanup meant for one decommissioned router had a filter that matched all of Lyon: it set three services to `low` criticality and deleted `svc-pe-lys-02-2`, a critical one. No rule covers this, so every check passed and the change was merged.

In Git, `git revert` would undo the merge. Infrahub 1.11.9 has no revert: no button, no mutation, no command. `infrahub recover merge` only cleans up a merge that crashed half-way. A rollback in Infrahub is a new change, and the history holds everything needed to write it.

### The history keeps everything

Nothing was overwritten, and the UI shows it in three places:

1. **The time selector**, at the top left: set it to just before the merge (here in local time).
2. **The values at that time**: the deleted service is still there, critical.
3. **The activity of the object**: who deleted it, on `cleanup-lys` and then on `main` with the merge, and every value it had.

[![The deleted service read at the time before the merge: 1 the time selector, 2 its values, 3 its activity, deleted on cleanup-lys then on main](<https://blog.antoinekh.dev/assets/images/infrahub-branching/rollback-time-travel.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/rollback-time-travel.png>)

### The rollback is a change forward

A rollback takes four steps, and the [lab](<https://github.com/antoinekh/labs/tree/master/infrahub_branching>) has a script for the first three (`scenarios/rollback.py`):

> [!WARNING]
>
> **No automatic rollback in Infrahub 1.11.9**
>
> Infrahub has no revert of a merged change: no button, no mutation, no command. The rollback code inside Infrahub only cleans up a merge that crashed half-way (`infrahub recover merge`). To undo a merged change, you need your own script, or you rebuild the old values by hand.

1. **Find what changed on `main`.** A diff of `main` with itself, between a time before the merge and a time after it (`DiffUpdate`, then `DiffTree`), lists the objects that the merge touched.
2. **Read `main` as it was before.** Every query accepts a point in time, so the script reads each of these objects at the time before the merge.
3. **Write it back on a new branch.** On `rollback-cleanup-lys`, it sets the three criticalities back, creates `svc-pe-lys-02-2` again with its values and its device, and deletes any object that the merge added.
4. **Review and merge it like any other change.** The rollback goes through a proposed change, the checks run, and the reviewer sees exactly what goes back:

[![The rollback proposed change: svc-pe-lys-02-2 added again with its values, svc-pe-lys-03-1 from low back to critical](<https://blog.antoinekh.dev/assets/images/infrahub-branching/rollback-pc-diff.png>)](<https://blog.antoinekh.dev/assets/images/infrahub-branching/rollback-pc-diff.png>)

After the merge, `main` holds the mistake and its fix, one edge after the other:

```text
"main", "critical", "2026-10-27T17:42:35Z", "2026-10-30T07:35:00Z"
"main", "low",      "2026-10-30T07:35:00Z", "2026-10-30T07:47:18Z"
"main", "critical", "2026-10-30T07:47:18Z", NULL
```

### What to know before you rely on it

- **A deleted object comes back with a new id.** `svc-pe-lys-02-2` was `18e273d3…` and is now `18e33ebf…`. The rollback rebuilds its relationships inside Infrahub, but anything outside that kept the old id (a script, another inventory, a ticket) must look it up again, by name or by human-friendly id.
- **A rollback writes the old values back** over any later change to the same fields: read its diff before you merge it.
- **It is better than a backup restore**, which loses every change made since.

> [!NOTE]
>
> **How NetBox stores changes and rolls them back**
>
> NetBox keeps the current data in PostgreSQL tables, and an edit overwrites the row. The history lives beside the data: every change writes an `ObjectChange` record to the changelog, with the action, the user, the time, and a JSON snapshot of the object before and after the change. The changelog is kept 90 days by default (`CHANGELOG_RETENTION`). NetBox itself has no revert: the changelog tells you what to write back, and you write it.
>
> [NetBox Branching](<https://github.com/netboxlabs/netbox-branching>) adds a **Revert** button to a merged branch (since v0.3.0). It applies the inverse of the branch changes in reverse order: it creates the deleted objects again with their original attributes, sets the old values back, and deletes the objects that the branch created. The revert adds new records to the changelog and erases none. It works only while the branch schema exists: once the branch is archived, by hand or with `auto_archive_days`, it can no longer be reverted.
>
> |  | NetBox with NetBox Branching | Infrahub 1.11.9 |
> | --- | --- | --- |
> | Where the history lives | A changelog beside the data | In the data: every edge carries its time range |
> | How long | 90 days by default | No retention, never trimmed |
> | Read a past state | Rebuild it from the changelog | Any query with a point in time |
> | Undo a merged change | One Revert button, until the branch is archived | A new branch built from the history, by hand or by script |

## What the Community edition does not give you

Everything in this post ran on the Community edition: Infrahub under the Apache 2.0 license, with Neo4j Community, as in the release compose file. OpsMill sells an Enterprise edition, and the documentation of the tested version states that both editions have the same data management features: schema, branches, proposed changes, conflicts, history, checks, artifacts and generators. The differences are in governance, operations and scale, and some of them touch exactly the workflow of this post.

> [!WARNING]
>
> **Limits of the Community edition**
>
> **Governance**
>
> - **No enforced approvals.** Reviewers can approve or reject a proposed change, but nothing requires an approval before a merge, and nothing revokes an approval when the branch changes after it (`INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS` and `INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS` are Enterprise). I merged my maintenance change with no review at all. Only the checks and the permissions stand between a branch and `main`.
> - **No LDAP.** The Community edition has local accounts, OAuth2 and OIDC single sign-on, and role-based access control. LDAP sign-ins are refused with an "enterprise required" error.
> - **No log forwarding.** The export of audit events and application logs to a SIEM over syslog is accepted in the configuration but does nothing.
>
> **Database and scale**
>
> - **Sized for about 1,000 devices.** That is the guidance of the Infrahub documentation for the Community edition; Enterprise targets 10,000 and more. My large graph had 1,064 routers plus the 30 devices of the demo data, so it was just above that size.
> - **One CPU core for Neo4j.** The same documentation says that Neo4j Community runs on a single CPU core, so large merges and imports are bound by single-core performance whatever the size of the host. Enterprise runs queries and merges on several cores. All my merge, diff and delete times were measured on Community; I did not test Enterprise, so I cannot say how much faster they would be.
> - **No clustering, no high availability.** One Neo4j instance, scaled vertically. If it stops, Infrahub stops.
> - **One database user.** Neo4j Community has only the built-in `neo4j` user, so you cannot give a read-only account to someone who wants to look at the graph as I did above.
> - **No online backup and no forced checkpoint.** `neo4j-admin database backup` and the `db.checkpoint()` procedure are Neo4j Enterprise features. In Community, a consistent copy is an offline dump, with the application stopped. I hit the checkpoint limit myself when I measured the store size.
>
> **Support**
>
> - Community support is Discord and GitHub, best effort, with no response time.

For a lab, a pilot or a network of up to about 1,000 devices, none of this blocks you. For a large or critical production network, it is different: nothing enforces the "four eyes" rule that most change processes require, and a single Neo4j instance gives no high availability and merges bound to one CPU core.

## What to plan for

| Limit | What I saw |
| --- | --- |
| One level of branches, always from `main` | No stacked changes, no branch of a branch |
| No commits | No unit of change inside a branch, no revert of a merged change, no cherry-pick |
| A branch does not follow `main` | It reads `main` frozen at `branched_from` until you rebase, and nothing warns you |
| Diffs are stored | A diff weighs more than the change itself, and flows refresh it, sometimes by hand |
| Merges and rebases are serialized | One global lock for the instance, and each merge is slow |
| Deletes are slow | Slower than a create, even for an empty branch |
| History is never trimmed | No retention for `main`: only a branch delete or a rebase removes history |
| A crashed merge needs an operator | `MERGE_FAILED` and `infrahub recover merge` |
| No revert | A rollback is a new branch built from the history; deleted objects come back with a new id |
| Everything heavy is a Prefect flow | The client sees queue time and SDK polling on top of the work |

## What I take away

The branch model holds up. A branch is a filter on a temporal graph, not a copy: it costs almost nothing to open and it reads as fast as `main`. The temporal edge model is elegant, and it gives history and time travel almost for free: "what did the source of truth say last night?" is one query. That is the right foundation for data that automation reads all day.

The cost sits in the life of a branch, and it is predictable. Merges run one at a time under a global lock, diffs and deletes take real work, and history only grows. A team that merges a few changes a day will not notice. A platform that opens a branch per change must be sized for merges and deletes, not for creations, and must know who recovers a failed merge.

The real gain comes from what a branch makes possible. An engineer prepares a maintenance where it cannot hurt anyone, a few lines of Python tell them before the merge that a PE would lose its last route reflector, and the change reaches the network already checked. The customers behind that PE never see the mistake, and when one still gets through, the history holds everything needed to write it back. Two conditions decide whether you get there: the schema must model the dependencies that your rules need, because Infrahub only knows what you put in the graph, and on a large or critical network, the Community edition leaves the four-eyes rule and high availability to you.

The next post follows the dependencies instead of the branches: [Which services sit behind this router? Infrahub Graph Traversal](<https://blog.antoinekh.dev/posts/infrahub-graph-traversal/index.md>).

## Bugs found along the way

I reported to OpsMill each bug I hit while writing this post, and sent a fix for each one.

> [!CAUTION]
>
> **Issues and pull requests**
>
> | Bug | Issue | Fix |
> | --- | --- | --- |
> | A check stays "in progress" forever when one of its runs fails or times out, and blocks the merge ([CI on a branch](<#ci-on-a-branch-custom-checks>)) | [\#11277](<https://github.com/opsmill/infrahub/issues/11277>) | [\#11279](<https://github.com/opsmill/infrahub/pull/11279>) |
> | A time-range diff of `main` reports an object deleted by a merge as updated | [\#11344](<https://github.com/opsmill/infrahub/issues/11344>) | [\#11348](<https://github.com/opsmill/infrahub/pull/11348>) |
> | A time-range diff of `main` reports the first value ever, not the value at the start of the range, as the previous value of a deleted object | [\#11345](<https://github.com/opsmill/infrahub/issues/11345>) | [\#11349](<https://github.com/opsmill/infrahub/pull/11349>) |
> | The same stale previous value for the properties of a removed relationship peer, found in the review of \#11349 | [\#11358](<https://github.com/opsmill/infrahub/issues/11358>) | [\#11360](<https://github.com/opsmill/infrahub/pull/11360>) |
>
> OpsMill merged the four pull requests.
