139 lines
4.8 KiB
Rust
139 lines
4.8 KiB
Rust
//! # gitops - Event-Driven GitOps Orchestration with Adaptive Workflow Resolution
|
|
//!
|
|
//! A declarative GitOps automation framework that bridges rules (WHAT you want)
|
|
//! with environment capabilities (HOW it happens).
|
|
//!
|
|
//! ## Key Concepts
|
|
//!
|
|
//! - **Rules**: Declarative definitions of events, conditions, and actions (YAML/TOML/KCL)
|
|
//! - **Events**: Git pushes, alerts, health checks, schedules, webhooks, CI/CD pipeline events
|
|
//! - **Providers**: Support for GitHub, GitLab, Gitea, Forgejo, and Woodpecker CI
|
|
//! - **Environment**: Auto-detects available tools (ArgoCD, Flux, K8s, Docker, systemd, n8n)
|
|
//! - **Flow**: Adaptive resolution of HOW to execute based on available capabilities
|
|
//! - **Executors**: Implement actions using available tools with automatic fallback
|
|
//!
|
|
//! ## Quick Start
|
|
//!
|
|
//! ```no_run
|
|
//! use gitops::engine::GitOpsEngine;
|
|
//! use gitops::rule::RuleRegistry;
|
|
//! use std::path::Path;
|
|
//!
|
|
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! // Load rules from YAML
|
|
//! let rules = RuleRegistry::from_yaml(Path::new("gitops-rules.yaml"))?;
|
|
//!
|
|
//! // Create engine (auto-detects environment)
|
|
//! let engine = GitOpsEngine::new(rules).await?;
|
|
//!
|
|
//! // Run the engine
|
|
//! engine.run().await?;
|
|
//!
|
|
//! # Ok(())
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! ## Supported Git Providers
|
|
//!
|
|
//! - **GitHub**: Full API support via octocrab
|
|
//! - **GitLab**: Full API support via gitlab crate
|
|
//! - **Gitea**: Full API support via gitea-rs
|
|
//! - **Forgejo**: Gitea-compatible API (self-hosted Git forge)
|
|
//! - **Woodpecker CI**: Pipeline orchestration and webhook integration
|
|
//!
|
|
//! ## Supported Event Sources
|
|
//!
|
|
//! - **Git**: Push, PR, tag, and branch events from any provider
|
|
//! - **Woodpecker**: Pipeline runs, status changes, and completion events
|
|
//! - **Alert**: Prometheus/Alertmanager webhook events
|
|
//! - **Schedule**: Cron-based scheduled events
|
|
//! - **Health**: observability crate health check events
|
|
//! - **n8n**: Workflow completion events
|
|
//! - **Manual**: CLI/API-triggered events
|
|
//! - **Webhook**: Generic HTTP webhook events
|
|
//!
|
|
//! ## Rule Example
|
|
//!
|
|
//! ```yaml
|
|
//! rules:
|
|
//! - name: deploy-on-merge
|
|
//! when:
|
|
//! event: git
|
|
//! type: pr_merged
|
|
//! branch: main
|
|
//! then:
|
|
//! action: deploy
|
|
//! environment: staging
|
|
//! - name: trigger-woodpecker-on-push
|
|
//! when:
|
|
//! event: git
|
|
//! type: push
|
|
//! branch: develop
|
|
//! then:
|
|
//! action: trigger-pipeline
|
|
//! provider: woodpecker
|
|
//! ```
|
|
//!
|
|
//! The engine automatically chooses HOW to deploy based on what's available:
|
|
//! - ArgoCD? → Apply Application CRD
|
|
//! - Flux? → Apply GitRepository + Kustomization
|
|
//! - Kubernetes? → Apply manifests directly
|
|
//! - Docker? → Use container deployment
|
|
//! - Systemd? → Deploy as service
|
|
//! - Woodpecker? → Trigger CI/CD pipeline
|
|
//! - Fallback → Execute script
|
|
|
|
// ============================================================================
|
|
// INTERNAL DEPENDENCY FACADE
|
|
// ============================================================================
|
|
// Groups external dependencies by concern, reducing efferent coupling
|
|
mod deps;
|
|
|
|
// ============================================================================
|
|
// CORE TIER - No internal dependencies
|
|
// ============================================================================
|
|
pub mod config;
|
|
pub mod error;
|
|
|
|
// ============================================================================
|
|
// FUNCTIONAL MODULES - Internal implementation, organized by tier
|
|
// ============================================================================
|
|
// Most modules are internal implementation details. Only engine and a few
|
|
// core types are part of the public API.
|
|
|
|
pub(crate) mod environment;
|
|
pub(crate) mod event;
|
|
pub(crate) mod executor;
|
|
pub(crate) mod flow;
|
|
pub(crate) mod generator;
|
|
pub mod integration;
|
|
pub(crate) mod provider;
|
|
pub(crate) mod rule;
|
|
|
|
// ============================================================================
|
|
// ORCHESTRATION TIER - Main coordination (only stable exports here)
|
|
// ============================================================================
|
|
pub mod engine;
|
|
|
|
// ============================================================================
|
|
// PUBLIC API - Stable interface (minimal, intentional exposure)
|
|
// ============================================================================
|
|
// Only types needed by external users are re-exported here.
|
|
// Internal implementation details remain private to reduce coupling.
|
|
|
|
/// Result type for all GitOps operations
|
|
pub use error::{GitOpsError, GitOpsResult};
|
|
|
|
/// Main entry point for GitOps operations
|
|
pub use engine::GitOpsEngine;
|
|
|
|
/// Engine configuration
|
|
pub use config::Config;
|
|
|
|
/// Library version
|
|
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
// Tests would go here
|
|
}
|