11: GitOps Repository Structure & CI/CD Foundations¶

This section defines how your entire LocalCloudLab project is organized in Git. It establishes:

• Directory structure
• YAML layout
• Naming conventions
• Branching strategy
• CI/CD structure (without writing workflows yet)
• Git pull strategies on the server
• Preparation for future GitOps (ArgoCD/Flux)

Your Git repository becomes the single source of truth for:

✔ Kubernetes manifests
✔ API projects
✔ Infrastructure configuration
✔ CI/CD workflows
✔ Documentation
✔ Versioning & release flow

This is one of the most important sections of the entire LocalCloudLab documentation.

11.1 Repository Top-Level Structure (Monorepo Model)¶

LocalCloudLab uses a monorepo. That means:

• All microservices live in the same repo
• All Kubernetes YAML lives in the same repo
• CI/CD pipelines trigger based on directory changes
• Easier cross-service consistency
• Easier environment management

Recommended root structure:

/
├── Search.Api/                     # .NET 9 API project
├── Checkin.Api/                    # .NET 9 API project
├── Shared/                         # Shared libraries (optional)
│   ├── Logging/
│   ├── Common/
│   └── Integrations/
├── k8s/                            # Kubernetes infrastructure
│   ├── gateway/                    # Envoy Gateway + HTTPRoutes
│   ├── namespaces/                 # Namespace definitions
│   ├── cert-manager/               # Issuers, Certificates
│   ├── metallb/                    # Load balancer config
│   ├── monitoring/                 # Prometheus + Grafana
│   ├── redis/                      # Redis install & config
│   ├── rabbitmq/                   # RabbitMQ install & config
│   ├── postgres/                   # PostgreSQL install
│   ├── search-api/                 # Search API Deployment + Service + Config
│   ├── checkin-api/                # Checkin API Deployment + Service + Config
│   └── base/                       # Future GitOps base manifests (optional)
├── .github/
│   └── workflows/                  # CI/CD pipelines (YAML)
├── docs/                           # Additional documentation
├── scripts/                        # Utility scripts for server automation
└── README.md

11.1.1 Why this layout works perfectly¶

The structure has the following benefits:

✔ Easy navigation — everything is where you expect it
✔ Each API has its own manifests (deployment, service, config)
✔ Infrastructure is cleanly separated
✔ cert-manager, envoy, redis, rabbitmq all isolated in folders
✔ GitHub Actions can use path filters to deploy only updated APIs
✔ Easy migration to GitOps (ArgoCD/Flux) in the future
✔ CI/CD becomes predictable and scalable

11.1.2 Namespace Folder Structure¶

Namespaces are declared once and used everywhere:

k8s/namespaces/
├── search-namespace.yaml
├── checkin-namespace.yaml
├── monitoring-namespace.yaml
├── caching-namespace.yaml
├── messaging-namespace.yaml
└── database-namespace.yaml

Clean namespaces benefit you:

• Better isolation
• Easier monitoring per area
• Cleaner permissions (RBAC)
• Predictable resource grouping

11.2 Naming Conventions (Critical for Long-Term Stability)¶

Names affect:

• Monitoring
• Scaling
• Deployments
• CI/CD logs
• Secret management
• GitOps tools

11.2.1 Kubernetes Naming Rules¶

General rules:

• Use lowercase
• Use hyphens (not underscores)
• No spaces
• No capital letters
• No special characters

Correct:

search-api
search-api-deployment
search-api-svc

Incorrect:

Search_API
SearchApiService

11.2.2 Naming Conventions for LocalCloudLab¶

Namespaces:

search
checkin
messaging
caching
monitoring
database
envoy-gateway-system
cert-manager

Deployments:

<service>-deployment

Example:

search-api-deployment

Services:

<service>-svc

Secrets:

<service>-secret
<service>-connection

ConfigMaps:

<service>-config

HTTPRoutes:

<service>-route

Gateway:

main-gateway

Certificates:

<domain>-tls
search-checkin-tls

11.2.3 Folder Naming Strategy

Folders follow the same logic:

k8s/search-api/
k8s/checkin-api/
k8s/gateway/
k8s/cert-manager/
k8s/postgres/
k8s/redis/
k8s/rabbitmq/

This keeps the entire project predictable.

11.3 Multi-Environment Strategy (Optional Future)¶

You can optionally extend the repo later to:

k8s/environments/
├── dev/
├── staging/
└── production/

But for LocalCloudLab on a single cluster, this is optional.

We keep things simple now.

11.4 Branching Strategy for LocalCloudLab¶

A clean branching strategy prevents chaos.

Recommended:

• main     → always stable
• dev      → development branch
• feature/* → individual features
• hotfix/* → production fixes

11.4.1 main branch¶

✔ Always stable
✔ Deployed automatically to local cluster
✔ Protected: PR required

11.4.2 dev branch¶

✔ Integration branch
✔ Developers push here freely
✔ CI builds but does NOT deploy automatically (optional)

11.4.3 feature branches¶

feature/search-cache
feature/envoy-gateway-update
feature/add-rabbitmq

Purpose:

✔ isolate new work
✔ prevent breaking dev
✔ easy to review

11.4.4 hotfix branches¶

hotfix/postgres-connection
hotfix/gateway-certs

Used for:

✔ urgent bug fixes
✔ patched directly into main

11.4.5 Pull Request Workflow

Standard PR process:

1. Developer pushes to feature branch
2. PR opened into dev or main
3. Automatic CI runs:
    • Build
    • Test
    • Containerize
4. Reviewer approves
5. Merge
6. Workflow triggers deployment depending on branch

This structure avoids mistakes, overwrites, and broken deployments.

(End of Part 1 — Part 2 will cover CI/CD workflow structure, path filtering, Git pull strategy on server, YAML versioning, and GitOps foundations.)