provisioning-platform/prov-ecosystem/crates/gitops/README.md

# gitops - Event-Driven GitOps Orchestration

A declarative GitOps automation framework that bridges rules (WHAT you want) with environment capabilities (HOW it happens).

## Core Principle

```
RULES (static) + ENVIRONMENT (dynamic) = FLOW (adaptive)
```

You declare **intents**, the engine resolves **implementations** based on available tools.

## Key Features

- **Declarative Rules**: Define events, conditions, and actions in YAML/TOML/KCL
- **Event-Driven**: React to Git pushes, alerts, health checks, schedules, webhooks
- **Adaptive Execution**: Automatically chooses the best implementation based on available tools
- **Multi-Target Support**: ArgoCD, Flux, Kubernetes, Docker, systemd, n8n
- **Dynamic Environment Detection**: Continuously detects available capabilities
- **Fallback Chain**: Automatic fallback if primary executor unavailable
- **Multi-Provider Support**: GitHub, GitLab, Gitea with unified abstraction

## How It Works

### 1. Declare Rules (WHAT you want)

```yaml
# gitops-rules.yaml
rules:
  - name: deploy-on-merge
    when:
      event: pr_merged
      branch: main
    then:
      action: deploy
      environment: staging
```

The rule doesn't say HOW to deploy - that's adaptive.

### 2. Engine Detects Environment (Available tools)

The engine automatically detects what's available:

```rust
Environment detected:
  ✓ Docker
  ✓ Kubernetes
  ✓ ArgoCD
  ✗ Flux
  ✗ systemd
  ✓ n8n
```

### 3. Flow Resolution (HOW it happens)

When an event matches the rule, the engine resolves HOW to execute:

```
Event (pr_merged on main)
    ↓
Match Rule (deploy-on-merge)
    ↓
Resolve Flow with environment
    ├─ ArgoCD available? → Apply Application CRD
    └─ If ArgoCD fails → Try Kubernetes API
      └─ If K8s fails → Try Docker
        └─ Fallback → Execute script
    ↓
Execute Action (Deploy to staging)
```

## Adaptive Workflow Example

### Day 1: Local Development with Docker

```yaml
# Rules stay the same
rules:
  - name: deploy-on-push
    when: { event: push, branch: main }
    then: { action: deploy, environment: staging }
```

Engine detects: Docker available
→ Uses `docker-compose up`

### Day 30: Migrate to Kubernetes

Engine detects: Kubernetes available (Docker still there)
→ Automatically uses `kubectl apply`
**Rules unchanged!**

### Day 60: Adopt ArgoCD

Engine detects: ArgoCD available
→ Automatically generates Application CRD
**Rules still unchanged!**

## Rule Format

```yaml
rules:
  # Basic deployment rule
  - name: deploy-on-merge
    when:
      event: pr_merged
      branch: main
    then:
      - action: deploy
        environment: staging
      - action: notify
        target: slack

  # Automatic rollback on metrics
  - name: auto-rollback
    when:
      event: alert
      alert: HighErrorRate
      severity: critical
    then:
      - action: rollback
        environment: prod
      - action: notify
        message: "Rollback triggered"
        severity: critical

  # Scheduled backup
  - name: nightly-backup
    when:
      schedule: "0 2 * * *"
    then:
      - action: backup
        retention: 30d

  # Promotion with approval
  - name: promote-to-prod
    when:
      event: workflow_completed
      workflow: "staging-tests-passed"
    then:
      - action: deploy
        environment: prod
        require_approval: true
```

## Architecture

```
gitops/
├── rule/            # Declarative rules (YAML/TOML/KCL)
├── event/           # Event sources (git, alerts, webhooks, etc)
├── environment/     # Detects available capabilities
├── flow/            # Resolves HOW to execute
├── executor/        # Implements with detected tools
├── provider/        # Git provider abstractions
├── generator/       # Generates configs for external tools
└── integration/     # Integrations with ecosystem crates
```

## Capabilities Detected

| Capability | Usage |
|-----------|-------|
| **ArgoCD** | Deploy via Application CRDs |
| **Flux CD** | Deploy via GitRepository + Kustomization CRDs |
| **Kubernetes** | Deploy via kubectl directly |
| **Docker** | Deploy via runtime crate |
| **Podman** | Deploy via runtime crate |
| **systemd** | Deploy as service via init-servs crate |
| **n8n** | Notification and orchestration |
| **Prometheus** | Metrics-driven actions |

## Event Sources

- `git`: Push, PR, tag events (GitHub, GitLab, Gitea)
- `alert`: Prometheus/Alertmanager webhooks
- `schedule`: Cron expressions
- `health`: observability crate health events
- `n8n`: n8n workflow completions
- `manual`: CLI/API triggers
- `webhook`: Generic HTTP webhooks

## Integration with Ecosystem

| Crate | Integration |
|-------|-------------|
| **observability** | Health events trigger rules, expose metrics |
| **valida** | Validation rules in pipeline stages |
| **encrypt** | Secrets for actions |
| **runtime** | Container-based deployments |
| **init-servs** | systemd/launchd deployments |
| **backup** | Backup actions pre/post deploy |
| **n8n** | Workflow orchestration + notifications |

## Quick Start

### 1. Create rules file

```yaml
# gitops.yaml
rules:
  - name: deploy-staging
    when:
      event: push
      branch: main
    then:
      - action: deploy
        environment: staging
```

### 2. Use in Rust

```rust
use gitops::engine::GitOpsEngine;
use gitops::rule::RuleRegistry;
use std::path::Path;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load rules
    let rules = RuleRegistry::from_yaml(Path::new("gitops.yaml"))?;

    // Create engine (auto-detects environment)
    let engine = GitOpsEngine::new(rules).await?;

    // Run the engine
    engine.run().await?;

    Ok(())
}
```

### 3. Environment Auto-Detects

```
Detected capabilities:
  ✓ Kubernetes
  ✓ Docker
  ✓ ArgoCD
  ✓ Prometheus
  ✓ n8n
```

The engine automatically chooses the best implementation path for each action.

## Testing

```bash
cargo test -p gitops
# All 15 tests pass ✓
```

## License

MIT