Skip to content

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

What an Infrahub branch really is, what it costs, and where it stops.

Updated 26 min read
automation bgp ci infrahub neo4j source-of-truth

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 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, 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, the extension that adds branches to NetBox, and I wrote a plugin on top of it, 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?

Changelog

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. 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).

:NetDevice pe-par-01role: pe :NetDevice rr-lys-01role: rr :PEERS_WITH since: 2024 relationship: a type, a direction, its own properties svc-pe-par-01-1owner: noc :NetAppService :RUNS_ON A query is a pattern of the same shape: MATCH (s:NetAppService)-[:RUNS_ON]->(:NetDevice) -[:PEERS_WITH]->(:NetDevice {name: 'rr-lys-01'}) RETURN s.name

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:

Root NetDeviceuuid Attributename Attributestatus Relationshipdevice ↔ session AttributeValue"pe-par-01" AttributeValue"active" NetBgpSessionpe-par-01 → RR IS_PART_OF HAS_ATTRIBUTE HAS_ATTRIBUTE IS_RELATED IS_RELATED HAS_VALUE HAS_VALUE shared by every attribute set to active branch: main · branch_level: 1 from: 18:04:02 · to: null · status: active
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.

Attributestatus of p-bdx-01 AttributeValue"active" AttributeValue"maintenance" branch: main · branch_level: 1 from: 18:04:02 · to: null branch: large-0 · branch_level: 2 from: 18:15:22 · to: null read on main → active read on large-0 → maintenance

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.

changes on main after t1: invisible to the branch main branch status = active branch created status = maintenance owner changed rebase branched_from moves to t4 t0 t1 t2 t3 t4 read on the branch = main as of branched_from + the branch edges as of now

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:

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
"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

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:

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, 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.

clientSDK or UI API server4 gunicorn workers task managerPrefect: queue task worker× 2: runs the flow RabbitMQrefresh registry Redisdistributed lock Neo4j+1 node, +1 edge polls 1 2 3 4 5 6

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 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.

the change: 1 edge the stored diff: 3 nodes and 3 edges per change Attributeowner AttributeValue"team-noc-10" HAS_VALUE branch: bulk-10 DiffRootbulk-10 DiffRootmain partner the changes of main over the same time range, to detect conflicts DiffNodesvc-pe-bdx-04-1 DiffAttributeowner DiffPropertyteam-bdx → team-noc-10 DIFF_HAS_NODE DIFF_HAS_ATTRIBUTE DIFF_HAS_PROPERTY DiffConflictmain vs branch DIFF_HAS_CONFLICT if main changed it too repeated for every changed attribute one attribute change on the bulk-10 branch and the diff that Infrahub stores for it

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.
global merge lock: no other merge or rebase on the instance 1take the lock 2block writes 3revalidate 4write latestvalues on main 5close oldmain edges 6branchMERGED main and the source branch refuse writes: HTTP 423 worker dies → branch MERGE_FAILED, main stays blocked → infrahub recover merge

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

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

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

Editing rr-lys-01 on the branch

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

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

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

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
---
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
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
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

The gate

branchmaint-rr-lys-01 proposedchange ✓ Data integrity ✓ Schema integrity ✗ user check: 8 PEspe_route_reflector_redundancy mergerefused fix on the branch: backup sessions to rr-mrs-01, checks run again, pass in 10 s, merge

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

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

Merge refused: Unable to merge proposed change containing failing checks

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

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

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

The rollback is a change forward

read only: the history of main a normal change: the same gate as any other 1diff mainbefore → afterwhat changed 2read mainat beforethe old values 3write them backon a new branchrollback-… 4proposed changechecks, reviewmerge scenarios/rollback.py does steps 1 to 3 set values back · create deleted objects again (new id) · delete added objects

A rollback takes four steps, and the lab has a script for the first three (scenarios/rollback.py):

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

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

criticality of svc-pe-lys-03-1 on main critical low critical main cleanup-lys rollback-cleanup-lys bad merge, 07:35 UTC rollback merge, 07:47 UTC svc-pe-lys-02-2 on main id 18e273d3… deleted id 18e33ebf… the rollback adds edges to main: the history keeps the mistake and its fix
"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.
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 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.

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.

Bugs found along the way

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

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) #11277 #11279
A time-range diff of main reports an object deleted by a merge as updated #11344 #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 #11349
The same stale previous value for the properties of a removed relationship peer, found in the review of #11349 #11358 #11360

OpsMill merged the four pull requests.