Git Integration & Synchronization
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub integrates Git-like branching and version control with a graph database (Neo4j) to manage infrastructure data. The system synchronizes remote Git repositories with Infrahub branches, facilitating code-driven infrastructure management, automated artifact regeneration, and repository lifecycle management.
Sources: AGENTS.md:1-5, dev/knowledge/backend/git-sync.md
Repository Architecture
The core Git logic resides in the backend/infrahub/git/ module. The architecture is primarily structured around large classes that handle repository operations, although it is undergoing refactoring to align with SOLID principles.
Key Components
- InfrahubRepositoryBase: Manages basic repository information, configuration parsing, and local checkout management.
- InfrahubRepositoryIntegrator: Extends the base class to handle complex integration tasks, including artifact rendering, dynamic Python loading, and schema imports.
- InfrahubRepository / InfrahubReadOnlyRepository: The primary interfaces for interacting with standard and read-only repositories.
- RepositoryFileImporter: A collaborator class extracted to handle file discovery and specific object type imports (e.g., schemas, GraphQL queries, transforms).
Sources: specs/infp-546-git-solid-refactor/plan.md:10-25, backend/infrahub/git/repository.py
Responsibility Mapping
| Component | Responsibility |
|---|---|
| Config Parsing | Interpreting .infrahub.yml and repository settings. |
| File Discovery | Locating and identifying files within the local Git checkout. |
| Object Lifecycle | Managing the creation and deletion of nodes based on Git history. |
| Artifact Rendering | Executing transformations to generate infrastructure artifacts. |
| Dynamic Loading | Loading Python-based checks and transforms at runtime. |
Sources: specs/infp-546-git-solid-refactor/plan.md:12-18
Synchronization & Branch Mapping
Infrahub maps remote Git branches to internal Infrahub branches. This synchronization ensures that the graph state reflects the versioned data stored in Git.
Data Flow
- Remote Import: Infrahub fetches updates from the remote Git repository.
- Branch Mapping: The system associates Git branches with Infrahub branch nodes in Neo4j.
- Syncing: Changes in Git (files, commits) are imported and represented as infrastructure nodes or attributes.
- Error Surfacing: Synchronization errors (e.g., authentication failures, invalid configuration) are surfaced to the user.
This diagram illustrates the flow from a Git remote to the internal graph representation and finally to the user interface.
Sources: dev/knowledge/backend/git-sync.md, backend/AGENTS.md:144-148
Artifact Regeneration Triggers
Infrahub automatically regenerates artifacts (generated files or values) when linked Git repositories change. This process is optimized to avoid unnecessary regeneration.
Regeneration Logic
Regeneration is gated by per-definition predicates against a diff_summary of Git changes:
- _query_changed: Triggers if the underlying GraphQL query for the artifact changes.
- _definition_changed: Triggers if the core artifact definition node ID is modified.
- _transform_changed: Triggers if the Jinja2 or Python transformation code is modified.
Dependency Tracking (Stage 2)
Infrahub uses dependencies and watch configurations to refine triggers:
- Automatic Closure: Jinja2 AST walks and Python package floor discovery build a list of file dependencies.
- User Declaration: Users can explicitly define files to watch in
.infrahub.yml. - Selection Gate: The pipeline performs a set intersection between the stored file closure and the repository file diff.
This flowchart shows how Git changes are filtered through predicates and watch lists to determine if an artifact requires regeneration.
Sources: specs/infp-409-artifact-regen-triggers/plan.md:15-35
Branch Lifecycle Management
Git integration extends to the cleanup and lifecycle of branches within the infrastructure.
Automatic Deletion After Merge
Administrators can configure Infrahub to automatically delete branches after a successful merge.
| Setting | Type | Description |
|---|---|---|
main.delete_branch_after_merge | Boolean | Deletes the Infrahub branch node after merge. |
git.delete_git_branch_after_merge | Boolean | Deletes the corresponding remote Git branch after merge. |
Deletion Workflow
When a merge occurs, a BRANCH_DELETE task is submitted. If Git deletion is enabled, the GIT_REPOSITORIES_DELETE_BRANCH workflow fans out to individual git_branch_delete tasks for every linked repository.
# Implementation of Git branch deletion trigger
# backend/infrahub/core/branch/tasks.py
if config.SETTINGS.git.delete_git_branch_after_merge and obj.sync_with_git:
await submit_workflow(
name="GIT_REPOSITORIES_DELETE_BRANCH",
parameters={"branch": obj.name}
)
Sources: specs/infp-389-branch-merge-delete/tasks.md:45-75, specs/infp-389-branch-merge-delete/plan.md:30-45
Submodule Management
Infrahub manages specific components, like the python_sdk, as Git submodules. Submodule versions are strictly tracked based on the parent repository's branch.
- develop branch: Tracks
origin/infrahub-develop. - stable branch: Tracks
origin/stable.
Standard Git commands (git submodule update --init --recursive) are required to sync these components during local development.
Sources: dev/guidelines/git-workflow.md:42-55, AGENTS.md:105-115
Conclusion
Git Integration & Synchronization in Infrahub serves as the bridge between versioned source code and the live infrastructure graph. By utilizing refined regeneration triggers, automated branch lifecycle tasks, and structured repository architectures, Infrahub ensures infrastructure state remains consistent, efficient, and traceable.
Sources: specs/infp-409-artifact-regen-triggers/plan.md, dev/knowledge/backend/git-sync.md