Branch Management Module
Relevant source files
The following files were used as context for generating this wiki page:
The Branch Management Module enables the creation, update, and deletion of branches within Infrahub via Ansible. It ensures that infrastructure data changes occur within controlled, isolated environments before being merged into a main branch.
This module belongs to the category of stateful CRUD operations in the opsmill.infrahub collection. It follows a consistent architectural pattern to maintain idempotency and precise state management.
Sources: plugins/module_utils/branch.py:15-18, AGENTS.md:104
Architecture and Design Patterns
The Branch Management Module utilizes the Module-utils pattern, one of the two core plugin patterns defined in the project constitution. In this pattern, the module stub (located in plugins/modules/branch.py) handles argument validation and documentation, while the actual execution logic resides in a subclass of InfrahubModule within plugins/module_utils/branch.py.
Sources: dev/constitution.md:43-51, dev/knowledge/plugin-patterns.md:7-9
Key Components
- BranchModule Class: The primary class responsible for executing branch-related logic. It inherits from
InfrahubModuleto leverage shared API clients and state management utilities. - InfrahubModule Base Class: Provides standardized methods for API interaction via the
InfrahubclientWrapper, handling idempotency and reporting changes. - InfrahubclientWrapper: Mediates all API calls to Infrahub, ensuring consistent error handling and security (e.g., token management).
Sources: plugins/module_utils/branch.py:15-18, dev/constitution.md:72-74, plugins/AGENTS.md:42-44
Execution Workflow
The module follows a "Fetch-Compare-Act" cycle to ensure idempotency. It first retrieves the current state of the branch from Infrahub, compares it against the desired state defined in the playbook, and only executes API mutations if a change is required.
This diagram illustrates the logical flow of the BranchModule.run() method, demonstrating how state is evaluated and acted upon.
Sources: plugins/module_utils/branch.py:22-38, dev/constitution.md:58-61
State Management
The module primarily manages two states for an InfrahubBranch object: present and absent.
| State | Action | Description |
|---|---|---|
present | _ensure_branch_exists | Creates the branch if it does not exist or updates it if parameters differ. |
absent | _ensure_branch_absent | Deletes the branch if it currently exists in the Infrahub instance. |
Sources: plugins/module_utils/branch.py:31-34, dev/knowledge/plugin-patterns.md:144-152
Idempotency Logic
If the module runs a second time with identical parameters, it yields changed: false. Mutations are skipped when the branch already matches the desired configuration. When check_mode is enabled, the module simulates actions and reports expected changes without modifying the actual Infrahub instance.
Sources: dev/constitution.md:63-68
Configuration and Parameters
The module uses INFRAHUB_ARG_SPEC as a base for its argument specification. This ensures all Infrahub modules share common connection parameters.
Connection Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
api_endpoint | str | Yes | N/A | Endpoint of the Infrahub API (env: INFRAHUB_ADDRESS). |
token | str | Yes | N/A | API token for authentication (env: INFRAHUB_API_TOKEN). |
timeout | int | No | 10 | Request timeout in seconds. |
validate_certs | bool | No | True | Whether to validate SSL certificates. |
Sources: plugins/AGENTS.md:32-38, dev/knowledge/plugin-patterns.md:43-50
Module-Specific Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | The name of the branch to manage. |
state | str | No | The desired state (present or absent). Default is present. |
Sources: plugins/module_utils/branch.py:25-27, plugins/AGENTS.md:36
Implementation Details
The core logic resides in the run method, which handles parameter extraction, branch retrieval, and state enforcement.
# From plugins/module_utils/branch.py
def run(self) -> None:
data = self.data
branch_name = data.get("name")
if not branch_name:
self._handle_errors(msg="Missing required parameter: 'name'")
self.result: dict[str, Any] = {"changed": False}
self.branch = self._get_branch(name=branch_name)
if self.state == "present":
self._ensure_branch_exists(data=data)
elif self.state == "absent":
self._ensure_branch_absent(data=data)
serialized_object = str(self.branch)
self.result["branch"] = serialized_object
self.module.exit_json(**self.result)
Sources: plugins/module_utils/branch.py:22-38
Interaction Sequence
The following sequence diagram represents the interaction between the Ansible controller and the Infrahub API during a branch management operation.
This diagram visualizes how the BranchModule uses the InfrahubclientWrapper to communicate with the API while processing the user's requested state.
Sources: plugins/module_utils/branch.py:22-38, dev/constitution.md:72-74
Summary
The Branch Management Module provides a robust, idempotent way to handle Infrahub branches. By strictly adhering to the Module-utils pattern and centralized InfrahubclientWrapper, it ensures consistent behavior, secure credential handling, and reliable state enforcement across infrastructure automation workflows.