Skip to main content

How to Manage Branches

If you need to work with Infrahub's branch-based version control system, this guide shows you how to create, delete, and manage branches using the VSCode extension.

Prerequisites​

  • Infrahub VSCode extension installed
  • At least one configured Infrahub server
  • Appropriate permissions to create/delete branches on your server

Step 1: View existing branches​

To see all branches on a server:

  1. Open the Infrahub icon in the Activity Bar
  2. Expand the "Infrahub Servers" tree view
  3. Click on your server to expand it
  4. You'll see all branches listed with:
    • Branch name
    • "(default)" marker for the main branch
    • Branch metadata when available

Step 2: Create a new branch​

From the tree view​

  1. Right-click on your server in the Infrahub Servers view
  2. Select New Branch from the context menu
  3. Enter the branch name (for example, "feature-network-update")
  4. Optionally add a description
  5. Press Enter to create the branch

Naming conventions​

Follow these branch naming patterns for clarity:

  • feature-[description] - New features
  • fix-[issue-number] - Bug fixes
  • update-[component] - Updates to existing components
  • test-[scenario] - Testing branches
  • dev-[username] - Personal development branches

Example: feature-datacenter-schema

Step 3: Delete a branch​

To remove a branch you no longer need:

  1. Expand your server in the tree view
  2. Right-click on the branch to delete
  3. Select Delete Branch
  4. Confirm the deletion when prompted

Warning: Branch deletion is permanent. Ensure you've merged or saved any important changes before deleting.

Step 4: Work with branch-specific data​

Execute queries on specific branches​

When running GraphQL queries:

  1. Right-click on a query in the Infrahub YAML view
  2. Select Execute GraphQL Query
  3. Choose your server
  4. Select the target branch from the list
  5. The query runs against that branch's data

Compare data across branches​

To compare data between branches, execute the same query on different branches:

query BranchComparison {
  NetworkDevice {
    count
    edges {
      node {
        hostname {
          value
        }
        _updated_at
      }
    }
  }
}

Run this query on:

  1. Main branch - baseline data
  2. Feature branch - modified data
  3. Compare the results to see differences

Step 5: Branch workflow examples​

Feature development workflow​

  1. Create Feature Branch

    Name: feature-add-firewall-schema
    Description: Adding firewall device schema and relationships

  2. Develop and Test

    • Modify schemas
    • Test queries against the branch
    • Validate changes

  3. Merge Process

    • Review changes
    • Merge via Infrahub UI or API
    • Delete feature branch after merge

Hotfix workflow​

  1. Create Hotfix Branch

    Name: fix-device-status-issue
    Description: Urgent fix for device status validation

  2. Apply Fix

    • Make necessary corrections
    • Test on hotfix branch

  3. Deploy

    • Merge to main
    • Verify fix
    • Clean up branch

Step 6: Advanced branch management​

Working with long-lived branches​

For branches that persist over time:

# Document branch purposes in your project
# branches.yml
branches:
  - name: develop
    purpose: Integration branch for ongoing development
    merge_target: main
    
  - name: staging
    purpose: Pre-production testing
    merge_target: main
    
  - name: feature-q4-updates
    purpose: Q4 feature development
    merge_target: develop

Branch metadata tracking​

Track branch information in your queries:

query BranchInfo {
  Branch {
    edges {
      node {
        name
        description
        created_at
        branched_from
        is_default
        has_schema_changes
      }
    }
  }
}

Validation​

To ensure branch operations are working:

  1. Creation Verification: New branch appears in tree view immediately
  2. Query Testing: Execute a query against the new branch
  3. Deletion Confirmation: Deleted branch disappears from tree view
  4. Refresh Check: Tree view updates every 10 seconds automatically

Best practices​

Branch lifecycle​

  1. Create with descriptive names
  2. Develop in isolation
  3. Test thoroughly on the branch
  4. Review changes before merging
  5. Merge when ready
  6. Delete after successful merge

Naming strategy​

Use consistent prefixes:

  • feature- for new functionality
  • fix- for bug fixes
  • update- for updates
  • test- for experiments
  • release- for release preparation

Documentation​

Document active branches:

## Active Branches

### feature-network-redesign
- **Created**: 2024-01-15
- **Owner**: Network Team
- **Purpose**: Redesigning network schema for multi-vendor support
- **Target Merge**: 2024-02-01

### fix-validation-error
- **Created**: 2024-01-20
- **Owner**: DevOps
- **Purpose**: Fix schema validation for IP addresses
- **Target Merge**: ASAP

Troubleshooting​

Branch creation fails​

  • Check server permissions
  • Verify branch name doesn't already exist
  • Ensure valid characters in branch name (alphanumeric, hyphens, underscores)

Branch not appearing​

  • Wait 10 seconds for automatic refresh
  • Manually reload VSCode window if needed
  • Check server connectivity

Cannot delete branch​

  • Verify you have deletion permissions
  • Ensure branch isn't protected
  • Check if branch is the default branch (cannot be deleted)