Skip to main content

GitOps Workflow with Orchestr8

Overview​

Orchestr8 follows GitOps principles where your Git repository is the single source of truth for your platform configuration. This guide explains how to set up and manage your GitOps repository and workflows.

Repository Architecture​

GitOps Repository Structure​

Your GitOps repository contains all the configuration for your Orchestr8 platform:

your-orchestr8-repo/
├── argocd-apps/           # ArgoCD Application definitions
│   ├── app-of-apps.yaml   # Root application
│   ├── platform/          # Core platform components
│   └── modules/           # Application modules
├── platform/              # Helm chart for platform services
│   ├── values.yaml        # Default configuration
│   ├── values-dev.yaml    # Development overrides
│   ├── values-staging.yaml # Staging overrides
│   └── values-prod.yaml   # Production overrides
├── modules/               # Application module definitions
│   ├── langfuse/          # Example module
│   └── voicefuse/         # Example module
└── environments/          # Environment-specific configurations
    ├── dev/
    ├── staging/
    └── production/

Repository Setup Options​

# Fork the main Orchestr8 repository
gh repo fork killerapp/orchestr8 --clone
cd orchestr8

# This gives you all example configurations and templates
# Create a new private repository for your organization
gh repo create your-org/your-platform-config --private

# The o8 setup command can initialize this repository
o8 setup --provider local --github-org your-org --repo-name your-platform-config

Option 3: Use Template (Advanced)​

# Use the main repo as a GitHub template
gh repo create your-org/your-platform-config --template killerapp/orchestr8

GitHub Authentication Setup​

Why Authentication is Required​

During o8 setup, you'll be prompted for GitHub authentication because:

  1. ArgoCD Repository Access: ArgoCD needs read access to your GitOps repository to sync configurations
  2. GitOps Principle: All platform configuration is stored in Git (no configuration in the cluster itself)
  3. Continuous Deployment: Changes to your repository automatically deploy to your cluster

Authentication Methods​

  • Most Secure: Uses GitHub's device flow for authentication
  • User-Friendly: Browser-based login flow
  • Scoped Access: Only requests necessary permissions
o8 setup --provider local --github-org your-org
# Follow the browser authentication flow

Method 2: Personal Access Token​

  • Headless Environments: Works in CI/CD and scripts
  • Manual Setup: Requires creating token beforehand
# 1. Create a GitHub Personal Access Token with 'repo' scope
# 2. Export it as environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# 3. Run setup
o8 setup --provider local --github-org your-org --github-token $GITHUB_TOKEN

Understanding the Authentication Flow​

When you run o8 setup, here's what happens:

o8 setup --provider local --github-org your-org

Step 1: Repository Discovery

GitHub organization: your-org
Checking repository: https://github.com/your-org/orchestr8

Step 2: Authentication Prompt

⚠️  GitHub authentication is required
ArgoCD needs access to the orchestr8 repository

Authentication options:
  1. OAuth Device Flow (recommended - secure & easy)
  2. Personal Access Token (manual setup)

Choose authentication method [1]:

Step 3: Repository Configuration

  • Orchestr8 configures ArgoCD to monitor your repository
  • Creates the necessary secrets for repository access
  • Sets up webhook subscriptions (if using GitHub App)

Branch Strategy​

Standard Git Flow​

feat/*          → Development environment (ephemeral)
staging         → Staging environment (persistent)
main            → Production environment (persistent)

Environment Mapping​

  • Development: Feature branches deployed to *-dev namespaces
  • Staging: Staging branch deployed to *-staging namespaces
  • Production: Main branch deployed to production namespaces

ArgoCD Project Structure​

1. Development Project (dev-project)​

  • Purpose: Testing feature branches and experimental changes
  • Permissions: Relaxed, allows auto-sync
  • Namespaces: *-dev, *-test, *-feat-*
  • Source Repos: Any GitHub repository (including forks)

2. Staging Project (staging-project)​

  • Purpose: Pre-production testing and validation
  • Permissions: Moderate, requires manual sync for critical changes
  • Namespaces: *-staging, *-uat
  • Source Repos: Main organization repositories only

3. Production Project (production-project)​

  • Purpose: Live production workloads
  • Permissions: Strict, manual sync only
  • Namespaces: Production namespaces
  • Source Repos: Main branch of approved repositories only

Deployment Workflow​

1. Feature Development​

# Developer workflow
git checkout -b feat/new-feature
# Make changes to module configurations
git commit -m "feat: add new feature configuration"
git push origin feat/new-feature

ArgoCD automatically detects the branch and deploys to development environment.

2. Staging Promotion​

# Merge to staging branch
git checkout staging
git merge feat/new-feature
git push origin staging

3. Production Release​

# Merge to main branch
git checkout main
git merge staging
git tag v1.2.3
git push origin main --tags

Advanced GitOps Patterns​

App-of-Apps Pattern​

Orchestr8 uses the "App-of-Apps" pattern where a root ArgoCD Application manages other Applications:

# argocd-apps/app-of-apps.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: orchestr8-platform
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/your-org/orchestr8
    path: argocd-apps
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Multi-Environment Support​

Each environment has its own values file:

# platform/values-dev.yaml
global:
  environment: development
  domain: dev.your-domain.com

# platform/values-prod.yaml
global:
  environment: production
  domain: your-domain.com

Security Considerations​

Repository Access​

  • Use private repositories for production configurations
  • Implement branch protection rules
  • Require code reviews for main branch changes
  • Use signed commits for production releases

Secret Management​

  • Never store secrets in Git repositories
  • Use External Secrets Operator with cloud secret stores
  • Rotate access tokens regularly
  • Monitor repository access logs

Troubleshooting GitOps Issues​

Common Problems​

Repository Not Syncing

# Check ArgoCD application status
kubectl get applications -n argocd

# View application details
argocd app get orchestr8-platform

# Force sync
argocd app sync orchestr8-platform

Authentication Failures

# Check repository credentials
kubectl get secrets -n argocd | grep repo

# Update repository credentials
argocd repo add https://github.com/your-org/orchestr8 --username your-user --password your-token

Branch Not Deploying

  • Check ArgoCD project permissions
  • Verify branch exists and has valid configurations
  • Check namespace permissions and RBAC rules