Branch Management
Relevant source files
The following files were used as context for generating this wiki page:
Branch Management in the Infrahub Python SDK provides the interface for interacting with branches in a remote Infrahub instance. It allows users to create, list, rebase, merge, and delete branches to manage infrastructure data changes in an isolated environment. The system ensures that every public feature is available through both asynchronous (InfrahubClient) and synchronous (InfrahubClientSync) clients to maintain API parity.
Sources: infrahub_sdk/branch.py:65-189, dev/constitution.md:52-60
Architecture and Client Interface
The branch management system follows a layered architecture where reusable logic resides in the SDK (infrahub_sdk/), and the CLI (infrahub_sdk/ctl/) acts as a thin layer over it. The SDK exposes two primary managers for branch operations: InfrahubBranchManager for asynchronous calls and InfrahubBranchManagerSync for synchronous operations.
Sources: dev/constitution.md:79-88, infrahub_sdk/branch.py:65-189
Implementation Structure
The managers interact with the Infrahub backend via GraphQL mutations and queries. The InfrahubClient handles the execution of these rendered GraphQL statements.
Sources: infrahub_sdk/branch.py:65-189
Data Models
Branches are represented by the BranchData Pydantic model, which encapsulates metadata including identification, status, and origin information.
BranchData Fields
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the branch. |
name | str | The name of the branch. |
description | str | None | A brief description of the branch's purpose. |
sync_with_git | bool | Indicates if Infrahub creates the branch in connected Git repositories. |
is_default | bool | Whether this is the default branch for the instance. |
has_schema_changes | bool | Indicates if the branch contains modifications to the schema. |
status | BranchStatus | The current lifecycle state of the branch (e.g., OPEN, MERGED). |
branched_from | str | The timestamp or reference point where the branch originated. |
Sources: infrahub_sdk/branch.py:27-41
Lifecycle States
The BranchStatus enumeration defines the valid states a branch can occupy during its existence.
| Status | Description |
|---|---|
OPEN | The branch is active and accepting changes. |
NEED_REBASE | The branch has drifted from its origin and requires a rebase. |
MERGING | A merge operation is currently in progress. |
MERGED | The branch changes have been successfully integrated into the origin. |
MERGE_FAILED | Integration of the branch changes failed. |
DELETING | The branch is being removed from the system. |
Sources: infrahub_sdk/branch.py:16-24
Core Operations
Branch Creation
When you create a branch, the SDK sends a BranchCreate mutation. You can choose to wait for completion or receive a task ID for background processing. If sync_with_git is enabled, Infrahub extends the branch to connected repositories.
Sources: infrahub_sdk/branch.py:73-100, infrahub_sdk/ctl/branch.py:146-160
Rebase and Merge
The rebase and merge operations integrate changes between the branch and the main branch.
- Rebase: Updates the branch with the latest changes from the origin branch.
- Merge: Integrates changes from the feature branch back into the origin branch.
Sources: infrahub_sdk/branch.py:112-140, infrahub_sdk/ctl/branch.py:170-188
CLI Commands
The infrahubctl utility provides a sub-app for branch management, registered in infrahub_sdk/ctl/cli_commands.py.
| Command | Action |
|---|---|
list | Displays a table of all branches including their status and sync state. |
create | Creates a new branch with optional description and Git sync. |
delete | Removes a branch from the Infrahub instance. |
rebase | Performs a rebase of the specified branch with the main branch. |
merge | Merges the specified branch into the main branch. |
report | Generates a status report including diff summaries and proposed changes. |
Sources: infrahub_sdk/ctl/branch.py:112-258, infrahub_sdk/ctl/cli_commands.py:15-30
Reporting and Validation
The report command provides a comprehensive view of a branch's current state relative to the main branch. It retrieves a DiffTreeData object to summarize additions, deletions, updates, and conflicts. It also identifies proposed changes using the CoreProposedChange protocol.
Sources: infrahub_sdk/ctl/branch.py:200-258
Summary
Branch Management provides the necessary tooling for isolated development and data lifecycle management in Infrahub. By utilizing the SDK's dual-client architecture, developers can perform complex branching workflows programmatically or via the CLI, ensuring that infrastructure changes are validated and synced correctly with Git when required.
Sources: infrahub_sdk/branch.py:65-189, dev/constitution.md:52-60