Branch-Isolated Writes
Relevant source files
The following files were used as context for generating this wiki page:
Branch-Isolated Writes isolate infrastructure changes within dedicated session branches to protect the default branch from direct modification. The system automatically creates these branches on the first write operation, providing a human-approved review gate through the propose_changes workflow. This mechanism ensures that AI-driven infrastructure state changes remain audited and safe.
Sources: dev/constitution.md:27-38, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:58-62
Architecture and Core Principles
The architecture enforces branch safety by default for all tools tagged with "write". The system prevents direct writes to the instance's default branch, typically named main. Instead, write operations target a session-scoped branch derived from a configurable pattern.
Operational Principles
- Isolation by Default: All write operations MUST stay isolated within session branches.
- Lazy Creation: The server creates session branches only when the first write operation occurs in a session.
- Per-Session Scoping: Session branches and their associated states are scoped to individual MCP sessions rather than the entire server process.
- Read-Only Protection: When the server operates in
read_onlymode, it hides and rejects all write-tagged tools.
Sources: dev/constitution.md:27-38, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:104-106, specs/archive/20260604-141223-session-branch-recovery/spec.md:144-148
Branch State Management Flow
The following diagram illustrates how the system determines which branch to target during a write operation.
The diagram represents the decision logic used to ensure writes are isolated and redirected to writable session branches.
Sources: dev/constitution.md:27-41, specs/archive/20260604-141223-session-branch-recovery/spec.md:129-143
Session Branch Lifecycle
The session branch lifecycle begins when a tool requiring write access is invoked. The system resolves the appropriate branch and verifies its writability before executing the mutation.
Naming and Creation
Branches are created using a branch_pattern that supports placeholders for dynamic identification. If a branch name collision occurs, the system retries creation with a new hexadecimal value up to a configured maximum (max_branch_retries).
| Placeholder | Description |
|---|---|
{date} | Current date stamp. |
{hex} | Random hexadecimal value for collision avoidance. |
{user} | User identity extracted from OIDC JWT claims. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:65-72, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:108-112
Recovery and Reset Mechanisms
The server proactively monitors session branch writability to prevent write operations from becoming "wedged" if a branch is merged or deleted.
- Auto-Recovery: If a cached session branch is merged (read-only) or deleted, the system clears the session cache, provisions a new writable branch, and notifies the user of the new branch name.
- Manual Reset: Operators can use the
reset_session_branchtool to drop the current session's cached branch. - Explicit Override: Users can point the session to a specific branch name. The system validates these names against the
branch_patternbefore creation.
Sources: specs/archive/20260604-141223-session-branch-recovery/spec.md:129-158, specs/archive/20260604-141223-session-branch-recovery/tasks.md:46-51
Write Authorization Hardening
Write operations are strictly confined to authorized session branches. The system implements specific checks to prevent bypassing the review gate.
Mutation Restrictions
The mutate_graphql tool does not allow per-call branch overrides. It always targets the session branch to ensure isolation. Additionally, the system rejects "privileged" mutations that could modify the branch model or schema outside the standard review workflow.
This class diagram shows the relationship between write tools and the safety mechanisms that enforce branch isolation.
Sources: specs/archive/20260604-141223-session-branch-recovery/tasks.md:111-120, src/infrahub_mcp/tools/write.py
Protected Mutation Types
The system parses GraphQL queries to reject mutations that manage branches or the schema directly, including:
BranchCreate,BranchDelete,BranchMerge,BranchRebaseSchemaDropdown,SchemaEnummutations
Sources: specs/archive/20260604-141223-session-branch-recovery/spec.md:175-180, specs/archive/20260604-141223-session-branch-recovery/tasks.md:115-116
Summary
Branch-Isolated Writes provide a foundational safety layer for the Infrahub MCP server. By automating session branch creation and enforcing strict writability checks, the system prevents accidental corruption of production data. The combination of lazy branch creation, auto-recovery for merged branches, and mutation filtering ensures that all infrastructure changes remain traceable and subject to human approval through the proposal workflow.