Skip to main content

Selective branch synchronization

Infrahub automatically creates all branches from a connected Git repository by default. While this ensures full visibility, it can create unnecessary noise when many Git branches are unrelated to Infrahub data or workflows. Selective branch synchronization introduces an optional configuration that allows teams to control which Git branches are imported and synchronized into Infrahub based on custom naming patterns.

Why selective synchronization matters​

In real-world Git repositories, teams often maintain many branches for different purposes:

  • Development branches for features unrelated to infrastructure
  • Documentation-only branches
  • Experimental work that doesn't involve Infrahub data
  • Personal development branches
  • Archive branches kept for historical reference

When all these branches automatically sync to Infrahub, it creates:

  • Visual clutter: Branch lists become difficult to navigate with irrelevant entries
  • Performance overhead: Unnecessary synchronization consumes system resources
  • Workflow confusion: Team members may struggle to identify which branches contain infrastructure changes

Selective synchronization addresses these challenges by allowing administrators to define explicit rules for which branches should be imported and maintained in Infrahub.

How selective synchronization works​

The feature operates through a set of branch naming rules that determine which Git branches Infrahub will track and synchronize.

Default behavior​

By default, every branch created in your Git repository continues to be automatically imported and synchronized into Infrahub. No configuration changes are required for teams who want to maintain the current behavior.

This default ensures backward compatibility and zero-configuration operation for existing deployments.

Enabling selective synchronization​

When you enable selective branch synchronization, Infrahub will only import branches whose names match a set of user-defined rules. Each rule is a regular expression that defines a pattern for matching branch names.

info

Selective synchronization only affects the Git to Infrahub direction. Branches created in Infrahub with the "sync to Git" option enabled will still synchronize to Git normally.

Configuring selective synchronization​

Set the INFRAHUB_GIT_IMPORT_SYNC_BRANCH_NAMES environment variable (or the equivalent sync_branch_names key in infrahub.toml) to a JSON array of regular expression patterns:

INFRAHUB_GIT_IMPORT_SYNC_BRANCH_NAMES=["^infra/.*$","^feature/infrahub-.*$"]

A configuration change requires a restart of the Infrahub server. For detailed instructions on applying configuration changes to your deployment, see How to configure Infrahub.

How to configure Infrahub../deploy-manage/install-configure/configure-infrahub
Validation

After setting those variables and restarting, branch synchronization will follow the defined rules.

Rule processing​

Infrahub processes the rules in the order they appear in the configuration. The first matching expression determines whether a branch is synchronized.

Processing logic:

  1. When Infrahub discovers a branch in the Git repository, it evaluates the branch name against each rule in sequence
  2. The first rule that matches the branch name determines the outcome
  3. If a match is found, the branch will be created and synchronized in Infrahub
  4. If no match is found after checking all rules, the branch will be ignored

This top-to-bottom evaluation allows for fine-grained control over branch synchronization behavior.

Rule evaluation during updates​

When you modify the synchronization rules after a repository has been imported, Infrahub evaluates branches differently depending on their current state:

Adding patterns to expand scope:

If a Git branch exists but was not previously imported because it didn't match the old rules, and it now matches the updated rules, Infrahub will import that branch during the next synchronization cycle.

# Before
sync_branch_names = ["^infra/.*$"]

# After — network/topology and similar branches are now imported
sync_branch_names = [
  "^infra/.*$",
  "^network/.*$"
]

Removing patterns to restrict scope:

If a branch was already imported into Infrahub and has the "sync with Git" flag enabled, it will continue to synchronize even if it no longer matches the updated rules. This preserves existing work and prevents unexpected data loss.

# Before
sync_branch_names = [
  "^infra/.*$",
  "^feature/.*$"
]

# After — existing feature/* branches in Infrahub continue syncing
sync_branch_names = ["^infra/.*$"]

Cleaning up branches manually:

If you want to stop synchronizing branches that no longer match your rules:

  1. Navigate to Branches in the Infrahub UI
  2. Find the branch you want to remove and click the delete option
  3. Or delete branches programmatically via the API
Permanent deletion

Manually deleting branches in Infrahub is permanent. The deletion does not affect the corresponding Git branches, and they will not be re-imported because they no longer match your rules.

info

The synchronization rules only control initial import of branches from Git to Infrahub. Once a branch exists in Infrahub with Git synchronization enabled, it continues syncing regardless of rule changes.

Regular expression patterns​

Each rule uses standard regular expression syntax to define matching patterns. This approach provides maximum flexibility without enforcing a specific naming convention.

Common pattern elements you can use:

  • ^ - Match the beginning of the branch name
  • $ - Match the end of the branch name
  • .* - Match any characters (zero or more)
  • [a-z] - Match any lowercase letter
  • [0-9]+ - Match one or more digits
  • (feature|fix) - Match either "feature" or "fix"

Example 1: infrastructure-only branches​

Your team uses a naming convention where all infrastructure-related branches start with infra/.

Rule:

["^infra/.*$"]

Results:

Git Branch NameMatches Rule?Imported to Infrahub?
infra/network-update✅ Yes✅ Created in Infrahub
infra/add-devices✅ Yes✅ Created in Infrahub
docs/update-readme❌ No🚫 Not imported
feature/new-api❌ No🚫 Not imported

Example 2: multiple team prefixes​

Different teams use different prefixes for their infrastructure work.

Rules:

[
  "^infra/.*$",
  "^network/.*$",
  "^config/.*$"
]

Results:

Git Branch NameMatches Rule?Imported to Infrahub?
infra/devices✅ Yes✅ Created in Infrahub
network/topology✅ Yes✅ Created in Infrahub
config/templates✅ Yes✅ Created in Infrahub
docs/architecture❌ No🚫 Not imported

Example 3: feature branches with issue numbers​

Your workflow includes Infrahub-related feature branches that reference issue numbers.

Rule:

["^feature/infrahub-[0-9]+.*$"]

Results:

Git Branch NameMatches Rule?Imported to Infrahub?
feature/infrahub-321✅ Yes✅ Created in Infrahub
feature/infrahub-123-network✅ Yes✅ Created in Infrahub
feature/api-update❌ No🚫 Not imported
feature/device-backup❌ No🚫 Not imported

Verifying the configuration​

To verify that the selective synchronization rules are working correctly, you need a Git repository connected to Infrahub. If you haven't connected a repository yet, see How to connect external Git repositories.

Test with branches that should NOT be imported​

  1. Create a branch in your Git repository that doesn't match your rules:
git checkout -b docs/update-readme
git push origin docs/update-readme
  1. Wait a few seconds for the synchronization cycle to complete
  2. Check the Infrahub UI or API — this branch should not appear in Infrahub

Test with branches that SHOULD be imported​

  1. Create a branch in your Git repository that matches your rules:
git checkout -b infra/network-update
git push origin infra/network-update
  1. Wait a few seconds for the synchronization cycle to complete
  2. Check the Infrahub UI or API — this branch should appear in Infrahub

Verify using the Infrahub UI​

  1. Navigate to the Branches section in the Infrahub UI
  2. Confirm that only branches matching your rules are displayed

Verify using the API​

Query the GraphQL API to list all branches:

query {
  Branch {
    edges {
      node {
        name
      }
    }
  }
}

Only branches matching your configured rules should appear in the results.

Troubleshooting​

Branches not appearing after configuration​

Possible causes:

  • Infrahub services haven't been restarted after configuration changes
  • Regular expression pattern doesn't match the branch name
  • Synchronization cycle hasn't completed yet

Solutions:

  1. Verify the configuration is correct
  2. Restart Infrahub services
  3. Wait 10–15 seconds for the next synchronization cycle
  4. Test your regex pattern using an online regex tester

Branches still appearing after adding rules​

Possible causes:

  • The branches were already imported before you configured the rules
  • Branches have the "sync with Git" flag enabled
  • An environment variable is overriding the configuration file

Solutions:

  1. Check if an environment variable is set and taking precedence
  2. Delete existing branches manually if needed — rules only control new imports, not existing branches

All branches are being imported despite rules​

Possible causes:

  • Configuration not loaded correctly
  • Services not restarted
  • Syntax error in the configuration

Solutions:

  1. Check Infrahub logs for configuration errors
  2. Verify the TOML syntax is correct
  3. Verify the JSON syntax is correct for environment variables
  4. Restart services after any configuration change

Current scope and limitations​

Directional behavior​

Selective branch synchronization only affects the Git → Infrahub direction:

  • Git branches that don't match the rules will not be imported into Infrahub
  • Branches created in Infrahub with the "sync to Git" option enabled will still synchronize to Git normally
  • This asymmetric behavior allows teams to use Infrahub as the source of truth while filtering incoming Git branches

Dynamic updates​

When you modify the sync_branch_names configuration:

  • New Git branches will be evaluated against the updated rules during the next synchronization
  • Git branches that now match the rules will be automatically imported
  • Existing Infrahub branches with Git synchronization enabled continue syncing regardless of rule changes
  • Branches no longer matching the rules will not be automatically removed from Infrahub
  • You must manually delete branches in Infrahub if they no longer align with your synchronization policy

Repository types​

Selective branch synchronization applies to standard read-write repositories that support full bidirectional integration. Read-only repositories track a single reference and are not affected by this configuration.

Further reading​