Git Management

Prerequisites

Hyve uses your system’s git binary for all repository operations. Git must be installed and available in your PATH before using any hyve git commands.

# Verify git is installed
git --version

If git is not installed, download it from git-scm.com or install via your package manager:

# macOS
brew install git

# Ubuntu / Debian
sudo apt install git

# Windows
winget install Git.Git

Overview

Hyve uses Git repositories to store all cluster state, workflows, and templates. This guide covers repository management, branching, synchronization, and multi-environment workflows.

Repository Basics

Adding Repositories

Add a Git repository to store your infrastructure state:

# Add a repository
hyve git add production --repo-url https://github.com/company/hyve-prod.git

# Add and set as the active repository immediately
hyve git add staging \
  --repo-url https://github.com/company/hyve-staging.git \
  --set-current

Listing Repositories

hyve git list

Output:

📁 Configured Git repositories (3):

  production (current) ⭐
    URL: https://github.com/company/hyve-prod.git
    Local: /Users/username/.hyve/repositories/production
    Added: 2026-01-15 09:30

  staging
    URL: https://github.com/company/hyve-staging.git
    Local: /Users/username/.hyve/repositories/staging
    Added: 2026-01-15 09:32

  development
    URL: https://github.com/company/hyve-dev.git
    Local: /Users/username/.hyve/repositories/development
    Added: 2026-01-15 09:34

Switching Repositories

# Switch to a different repository
hyve git use staging

# Check current repository
hyve git status

Removing Repositories

# Remove a repository
hyve git remove development

# Reset all repositories (clean slate)
hyve git reset

Branch Management

Listing Branches

# List all branches
hyve git branch list

Output:

🌿 Branches in repository 'production':

  feature/add-staging-cluster (abc12345)
* main (def56789)
  feature/update-workflows (ghi90123)

Creating Branches

Basic

# Create a new branch
hyve git branch create feature/new-cluster

Create and Switch

# Create and switch to new branch
hyve git branch create feature/staging --switch

Create and Push

# Create, switch, and push to remote
hyve git branch create feature/updates --switch --push

Switching Branches

# Switch to existing branch
hyve git branch switch develop

# Switch and pull latest changes
hyve git branch switch main --pull

Deleting Branches

# Delete a branch
hyve git branch delete feature/old-config

# Force delete
hyve git branch delete feature/experimental --force

Synchronization

Pull Changes

Pull latest changes from the remote:

hyve git pull

Push Changes

Push local changes to the remote:

# Push with custom message
hyve git push "Updated cluster configuration"

# Push with default message (auto-generated from changes)
hyve git push

Sync (Pull + Push)

Synchronize both ways:

# Sync with custom message
hyve git sync --message "Synced infrastructure changes"

# Sync (pull only, no local changes to push)
hyve git sync

Workflow:

Pulls latest changes from remote
If local changes exist, commits them with your message
Pushes to remote

Authentication

Hyve delegates all git operations to the system git binary. Authentication is handled by git itself — configure it the same way you would for any other git workflow.

Recommended: Personal Access Token via Environment Variable

# Set for the current session
export HYVE_GIT_TOKEN=your_personal_access_token

# Persist in your shell profile
echo 'export HYVE_GIT_TOKEN=your_token' >> ~/.bashrc

Hyve reads HYVE_GIT_TOKEN and passes it to git when cloning and pushing.

Alternative: Git Credential Manager

Use git’s built-in credential storage so you don’t need to set environment variables:

# macOS — Keychain (usually preconfigured)
git config --global credential.helper osxkeychain

# Windows — Git Credential Manager (included with Git for Windows)
git config --global credential.helper manager

# Linux
git config --global credential.helper store

Once configured, git will prompt for credentials on first use and cache them automatically.

Alternative: SSH Keys

Use SSH URLs instead of HTTPS to authenticate with SSH keys:

hyve git add production --repo-url git@github.com:company/hyve-prod.git

Ensure your SSH key is added to your git host and loaded into ssh-agent:

ssh-add ~/.ssh/id_ed25519

Multi-Environment Workflows

Scenario: Dev, Staging, Production

Set up repositories

# Development
hyve git add development \
  --repo-url https://github.com/company/hyve-dev.git

# Staging
hyve git add staging \
  --repo-url https://github.com/company/hyve-staging.git

# Production
hyve git add production \
  --repo-url https://github.com/company/hyve-prod.git

Configure each environment

# Development clusters
hyve git use development
hyve cluster add dev-app --provider civo --region PHX1 --nodes g4s.kube.small

# Staging clusters
hyve git use staging
hyve cluster add staging-app --provider civo --region NYC1 --nodes g4s.kube.medium

# Production clusters
hyve git use production
hyve cluster add prod-app --provider civo --region NYC1 --nodes g4s.kube.large

Manage independently

Each repository maintains its own:

Cluster definitions
Workflows
Templates
Kubeconfigs (encrypted per repository)

Branch-Based Environments

Use branches within a single repository:

# Main repository
hyve git add infrastructure --repo-url https://github.com/company/infra.git

# Development branch
hyve git branch create develop --switch
hyve cluster add dev-cluster --provider civo --region PHX1 --nodes g4s.kube.small

# Staging branch
hyve git branch create staging --switch
hyve cluster add staging-cluster --provider civo --region NYC1 --nodes g4s.kube.medium

# Production in main
hyve git branch switch main
hyve cluster add prod-cluster --provider civo --region NYC1 --nodes g4s.kube.large

Repository Structure

Each repository follows this structure:

repository/
├── clusters/           # Cluster definitions
│   ├── production.yaml
│   ├── staging.yaml
│   └── dev-cluster.yaml
├── workflows/          # Workflow definitions
│   ├── deploy-app.yaml
│   ├── setup-monitoring.yaml
│   └── backup-db.yaml
├── templates/          # Cluster templates
│   ├── prod-template.yaml
│   ├── staging-template.yaml
│   └── dev-template.yaml
└── .gitignore         # Ignore temporary files

Best Practices

1. Use Descriptive Repository Names

# Good
hyve git add production-us-east
hyve git add production-eu-west
hyve git add staging-shared

# Avoid
hyve git add repo1
hyve git add my-clusters

2. Regular Synchronization

# At start of day
hyve git pull

# Before making changes
hyve git pull

# After making changes
hyve git push "Your changes description"

# Or use sync for both
hyve git sync --message "Daily sync"

3. Branch for Experimental Changes

# Create feature branch
hyve git branch create feature/test-new-cluster --switch

# Make changes
hyve cluster add test-cluster --provider civo --region PHX1 --nodes g4s.kube.small

# Test and verify
hyve reconcile

# Merge to main when ready
hyve git branch switch main
# Manually merge via Git or pull request

4. Separate Repositories for Environments

Use different repositories for different environments to:

Isolate configurations
Control access permissions
Prevent accidental changes
Enable different Git workflows per environment

5. Commit Messages

# Descriptive messages
hyve git push "Add production cluster for US region"
hyve git push "Update workflow to include monitoring setup"
hyve git push "Scale production cluster to 5 nodes"

# Avoid vague messages
hyve git push "Update"
hyve git push "Changes"

Troubleshooting

git: command not found

Problem: Hyve cannot find the git binary

Solution: Install git and ensure it is in your PATH:

# Verify installation
git --version

# macOS
brew install git

# Ubuntu / Debian
sudo apt install git

# Windows
winget install Git.Git

Authentication Failed

Problem: Git operations fail with authentication error

Solutions:

# Set token via environment variable
export HYVE_GIT_TOKEN=your_personal_access_token

# Or configure git credential manager
git config --global credential.helper osxkeychain  # macOS
git config --global credential.helper manager      # Windows

# For SSH: verify your key is loaded
ssh-add -l
ssh -T git@github.com

Merge Conflicts

Problem: Git pull fails due to conflicts

Solutions:

# Navigate to repository
cd ~/.hyve/repositories/production

# Check status
git status

# Resolve conflicts manually
# Edit conflicting files

# Commit resolution
git add .
git commit -m "Resolve merge conflicts"

# Push resolved changes
hyve git push "Resolved conflicts"

Repository Not Found

Problem: No Git repository configured error

Solution:

# Add a repository
hyve git add production --repo-url https://github.com/company/hyve-prod.git

# Verify it's added
hyve git list

# Set as active if needed
hyve git use production

Local Changes Conflict

Problem: Can’t switch repositories/branches with uncommitted changes

Solutions:

# Option 1: Commit and push changes
hyve git push "WIP: In progress work"

# Option 2: Stash changes manually
cd ~/.hyve/repositories/production
git stash
# Switch repositories/branches
# Later: git stash pop

# Option 3: Discard changes (careful!)
cd ~/.hyve/repositories/production
git reset --hard HEAD

Advanced Workflows

Team Collaboration

# Team member 1
hyve git pull                           # Get latest
hyve cluster add new-cluster            # Make changes
hyve git push "Add new cluster"         # Push changes

# Team member 2
hyve git pull                           # Pull changes from team member 1
# See new cluster automatically
hyve reconcile                          # Apply changes

Multi-Region Setup

# US Region
hyve git add us-infrastructure \
  --repo-url https://github.com/company/hyve-us.git

hyve cluster add us-cluster --provider civo --region NYC1 --nodes g4s.kube.large

# EU Region
hyve git add eu-infrastructure \
  --repo-url https://github.com/company/hyve-eu.git

hyve git use eu-infrastructure
hyve cluster add eu-cluster --provider civo --region FRA1 --nodes g4s.kube.large

Promotion Workflow

# Develop in dev repository
hyve git use development
hyve workflow create deploy-v2 --template deployment-pipeline

# Test in staging
# Copy workflow file to staging repo
cp ~/.hyve/repositories/development/workflows/deploy-v2.yaml \
   ~/.hyve/repositories/staging/workflows/

hyve git use staging
hyve git push "Add deploy-v2 workflow"
hyve workflow run deploy-v2 --cluster staging-cluster

# Promote to production after testing
cp ~/.hyve/repositories/staging/workflows/deploy-v2.yaml \
   ~/.hyve/repositories/production/workflows/

hyve git use production
hyve git push "Promote deploy-v2 workflow to production"

Cluster Management

Learn cluster operations

Workflow Management

Automate deployments

Module System

How credentials work with modules

CLI: Git Commands

Complete Git command reference

Git Management

Prerequisites

Overview

Repository Basics

Adding Repositories

Listing Repositories

Switching Repositories

Removing Repositories

Branch Management

Listing Branches

Creating Branches

Switching Branches

Deleting Branches

Synchronization

Pull Changes

Push Changes

Sync (Pull + Push)

Authentication

Recommended: Personal Access Token via Environment Variable

Alternative: Git Credential Manager

Alternative: SSH Keys

Multi-Environment Workflows

Scenario: Dev, Staging, Production

Branch-Based Environments

Repository Structure

Best Practices

Troubleshooting

Advanced Workflows

Team Collaboration

Multi-Region Setup

Promotion Workflow

Related