Repository Management

Overview

Hyve uses Git repositories as the single source of truth for all infrastructure state. It supports multiple repositories, allowing you to isolate environments (dev/staging/prod) with separate configurations and credentials.

Multi-Environment

Separate repositories for different environments

Version Control

Full Git history for audit trails and rollbacks

Team Collaboration

Pull requests and code reviews for infrastructure changes

SQLite Backend

Local database tracks repository configurations

Repository Structure

Each repository follows a standard structure:

my-hyve-repo/
├── clusters/           # Cluster definitions
│   ├── production.yaml
│   ├── staging.yaml
│   └── development.yaml
├── workflows/          # Workflow definitions
│   ├── deploy-app.yaml
│   ├── setup-monitoring.yaml
│   └── backup-db.yaml
└── templates/          # Cluster templates
    ├── prod-template.yaml
    └── dev-template.yaml

Note

Hyve automatically creates these directories when you add a repository.

Adding Repositories

Basic Repository

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

# This will:
# 1. Clone the repository to ~/.hyve/repositories/production/
# 2. Create standard directories (clusters/, workflows/, templates/)
# 3. Set it as the active repository

Private Repository

For private repositories, configure Git credentials first:

# Set global Git credentials
hyve git credentials --username myuser --password ghp_xxxxxxxxxxxx

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

SSH Repository

# Ensure SSH key is loaded
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa

# Add repository with SSH URL
hyve git add production --repo-url git@github.com:company/hyve-prod.git

Managing Repositories

List Repositories

# List all configured repositories
hyve git list

Output:

Repositories:
  * production (https://github.com/company/hyve-prod.git) [active]
    staging (https://github.com/company/hyve-staging.git)
    development (https://github.com/company/hyve-dev.git)

Switch Active Repository

# Switch to different repository
hyve git use staging

# All subsequent commands use the staging repository
hyve cluster list

Note

The active repository determines which clusters, workflows, and templates are used.

View Current Repository

# Show currently active repository
hyve git current

Output:

Current repository: production
URL: https://github.com/company/hyve-prod.git
Path: ~/.hyve/repositories/production

Remove Repository

# Remove repository configuration and local clone
hyve git remove development

# This deletes:
# - Repository configuration from database
# - Local clone at ~/.hyve/repositories/development/

Caution

Removing a repository deletes the local clone. Ensure changes are pushed to the remote first.

Multi-Repository Workflows

Environment Isolation

Separate repositories for each environment:

Production

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

hyve git use production

# Production cluster
hyve cluster add prod-app \
  --provider civo \
  --region NYC1 \
  --nodes g4s.kube.large,g4s.kube.large,g4s.kube.large

Staging

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

hyve git use staging

# Staging cluster
hyve cluster add staging-app \
  --provider civo \
  --region PHX1 \
  --nodes g4s.kube.medium,g4s.kube.medium

Development

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

hyve git use development

# Development cluster
hyve cluster add dev-app \
  --provider civo \
  --region LON1 \
  --nodes g4s.kube.small

Team Collaboration

Multiple team members work on the same repository:

Clone repository

# Team member A
hyve git add shared \
  --repo-url https://github.com/company/hyve-shared.git

Create feature branch

# Team member A creates branch
cd ~/.hyve/repositories/shared
git checkout -b add-monitoring-cluster

Make changes

# Add cluster definition
hyve cluster add monitoring --provider civo --region NYC1

Commit and push

# Commit changes
git add clusters/monitoring.yaml
git commit -m "Add monitoring cluster"
git push origin add-monitoring-cluster

Create pull request

Create PR on GitHub/GitLab for team review

Team member B reviews

# Pull changes
cd ~/.hyve/repositories/shared
git fetch origin
git checkout add-monitoring-cluster

# Review changes
cat clusters/monitoring.yaml

# Approve PR

Merge and reconcile

# After merge, pull main branch
git checkout main
git pull origin main

# Apply changes
hyve reconcile

Repository Storage

Repositories are stored in ~/.hyve/repositories/:

~/.hyve/repositories/
├── production/
│   ├── .git/
│   ├── clusters/
│   │   ├── prod-app.yaml
│   │   └── prod-db.yaml
│   ├── workflows/
│   │   └── deploy-app.yaml
│   └── templates/
│       └── prod-template.yaml
├── staging/
│   └── ...
└── development/
    └── ...

Database Storage

Repository configurations are stored in SQLite:

~/.hyve/repositories.db

Tables:
  - repositories (name, url, path, active)

Synchronization

Pull Changes

# Pull latest changes from remote
cd ~/.hyve/repositories/production
git pull origin main

# Or use Hyve command
hyve git sync production

Push Changes

# Hyve commands automatically commit changes
hyve cluster add new-cluster --provider civo --region PHX1
# Creates clusters/new-cluster.yaml and commits

# Push to remote
cd ~/.hyve/repositories/production
git push origin main

Tip

Set up automatic push in CI/CD to keep remote repository synchronized.

Advanced Patterns

Monorepo Pattern

Single repository for all environments with subdirectories:

hyve-infra/
├── production/
│   ├── clusters/
│   ├── workflows/
│   └── templates/
├── staging/
│   ├── clusters/
│   ├── workflows/
│   └── templates/
└── development/
    ├── clusters/
    ├── workflows/
    └── templates/

# Add with subdirectories
hyve git add production --repo-url https://github.com/company/hyve-infra.git --path production
hyve git add staging --repo-url https://github.com/company/hyve-infra.git --path staging

Per-Team Repositories

Different teams manage separate repositories:

# Platform team
hyve git add platform --repo-url https://github.com/company/platform-infra.git

# Application team
hyve git add application --repo-url https://github.com/company/app-infra.git

# Data team
hyve git add data --repo-url https://github.com/company/data-infra.git

Feature Branch Workflows

Use Git branches for experimental changes:

# Create feature branch
cd ~/.hyve/repositories/production
git checkout -b experiment-new-region

# Make experimental changes
hyve cluster add test-cluster --provider civo --region FRA1

# Test reconciliation
hyve reconcile --dry-run

# If successful, merge to main
git checkout main
git merge experiment-new-region
hyve reconcile

Best Practices

1. Separate Environments

Use different repositories for production, staging, and development:

hyve git add production --repo-url https://github.com/company/hyve-prod.git
hyve git add staging --repo-url https://github.com/company/hyve-staging.git
hyve git add development --repo-url https://github.com/company/hyve-dev.git

This provides isolation and prevents accidental cross-environment changes.

2. Use Protected Branches

Configure branch protection on production repositories:

• Require pull request reviews
• Require status checks to pass
• Require signed commits
• Prevent force pushes

3. Document Repository Purpose

Add README to each repository:

# Hyve Production Infrastructure

This repository contains Kubernetes cluster definitions for production.

## Clusters
- prod-app: Main application cluster
- prod-db: Database cluster

## Workflows
- deploy-app: Application deployment pipeline

4. Regular Synchronization

Keep repositories synchronized with remotes:

# Pull before making changes
cd ~/.hyve/repositories/production
git pull origin main

# Push after changes
git push origin main

5. Use .gitignore

Exclude sensitive or temporary files:

.gitignore

.env
.env.*
*.tmp
*.log

Troubleshooting

No repository configured

Error: No active repository configured

Solution:

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

Git authentication fails

Error: Failed to authenticate with repository

Solution:

# Configure credentials
hyve git credentials --username myuser --password ghp_xxxxxxxxxxxx

# Or use SSH
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa

Repository already exists

Error: Repository 'production' already exists

Solution:

# Remove existing repository first
hyve git remove production

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

Merge conflicts

Error: Merge conflict in clusters/production.yaml

Solution:

# Resolve manually
cd ~/.hyve/repositories/production
git status
# Edit conflicting files
git add .
git commit -m "Resolve merge conflict"

Related

GitOps Principles

Learn about GitOps

Git Management

Complete Git management guide

Clusters

Cluster definitions

CLI Git

Git command reference