Workflow System Architecture

The OSDU SPI Fork Management system implements a sophisticated workflow architecture that separates template development concerns from fork production operations. This design enables scalable deployment across multiple fork instances while maintaining centralized template management.

Workflow Architecture Pattern

Template-Workflows Separation

The system implements a clean separation between template development and fork production workflows:

graph TD
    A[Template Repository] --> B[.github/workflows/<br/>Template Development]
    A --> C[.github/template-workflows/<br/>Fork Production]

    C --> D[Fork Instance 1<br/>.github/workflows/]
    C --> E[Fork Instance 2<br/>.github/workflows/]
    C --> F[Fork Instance N<br/>.github/workflows/]

    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style B fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style C fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style D fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style E fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style F fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

Template Development Context

.github/workflows/ - Template management and maintenance
- Repository initialization and bootstrap workflows
- Template testing and validation workflows
- Template versioning and release management
- Development CI/CD pipelines

Fork Production Context

.github/template-workflows/ - Production fork operations
- Upstream synchronization workflows
- Build and validation workflows
- Release management for fork instances
- Monitoring and maintenance workflows

Core Workflow Categories

Synchronization Workflows

Daily Upstream Sync (sync.yml)

AI-powered daily synchronization with intelligent duplicate prevention that fetches upstream changes, analyzes them for conflicts, and creates integration PRs with conventional commit messages
- Trigger: Scheduled daily at midnight UTC with intelligent duplicate prevention
- State Management: Tracks sync state between runs to prevent duplicate PRs and issues
- Decision Logic: Updates existing branches when upstream advances, prevents duplicates for same SHA
- Integration: Three-branch safety pattern (fork_upstream → fork_integration → main)
- AI Features: Intelligent change analysis and conventional commit generation
- Conflict Handling: Automated detection with human-guided resolution
Detailed spec

Template Propagation (sync-template.yml)

Distributes template improvements across multiple fork instances with selective synchronization and automated validation
- Trigger: Weekly scheduled execution on Mondays at 8 AM UTC
- Scope: Selective file synchronization based on configuration rules
- Safety: Automated testing and validation before deployment
- Scalability: Supports unlimited fork instances with consistent patterns
Detailed spec

Validation Workflows

Pull Request Validation (validate.yml)

Comprehensive quality assurance system that enforces code standards, verifies build integrity, and ensures consistency across all changes
- Quality Gates: Multi-phase validation pipeline with adaptive rules
- Scope: Commit format, branch naming, build verification, conflict detection
- Intelligence: Context-aware validation for different contribution types
- Feedback: Detailed status reporting with actionable developer guidance
Detailed spec

Dependabot Automation (dependabot-validation.yml)

Automated dependency update validation with intelligent risk assessment and selective auto-merging for routine updates
- Automation: Validates and tests all Dependabot dependency updates
- Security: Comprehensive vulnerability assessment of new dependencies
- Intelligence: Risk-based auto-merging for low-impact updates
- Integration: Seamless coordination with main validation pipeline
Detailed spec

Build & Release Workflows

Project Build (build.yml)

Feature branch build verification with comprehensive testing, coverage analysis, and performance-optimized execution
- Focus: Rapid developer feedback for feature branch development
- Coverage: Unit tests, integration tests, and comprehensive quality metrics
- Performance: Intelligent caching and parallel execution strategies
- Support: Java/Maven projects with extensible patterns for other languages
Detailed spec

Semantic Release (release.yml)

Automated semantic versioning with conventional commit analysis, changelog generation, and coordinated release distribution
- Versioning: Release Please integration with conventional commit standards
- Coordination: Upstream version tracking and alignment strategies
- Documentation: Automated changelog and release notes generation
- Distribution: Package publication and artifact management
Detailed spec

Cascade Workflows

Integration Cascade (cascade.yml)

Multi-stage integration workflow that safely promotes changes through the three-branch strategy with comprehensive validation
- Flow: Systematic progression from fork_upstream → fork_integration → main
- Safety: Comprehensive testing and validation at each integration stage
- Flexibility: Manual execution with automated monitoring capabilities
- Tracking: Complete progress monitoring through GitHub Issues
Detailed spec

Cascade Monitoring (cascade-monitor.yml)

Intelligent monitoring system that detects completed synchronizations and automatically triggers cascade operations with SLA management
- Detection: Automated monitoring for completed upstream synchronizations
- SLA Management: Ensures cascade operations meet timing requirements
- Escalation: Proactive alerts and notifications for overdue operations
- Recovery: Automatic retry mechanisms with intelligent backoff strategies
Detailed spec

AI-Enhanced Integration Workflows

Cross-Platform Integration

OSDU GitLab Integration (osdu-alfi.yml)

AI-powered cross-platform workflow that enables seamless GitHub-to-GitLab contribution for OSDU community repositories
- Trigger: @alfi mentions in GitHub PR reviews, issue comments, or new issues
- AI Integration: Claude Code CLI with GitLab MCP server for intelligent automation
- Cross-Platform Sync: Creates GitLab branches and merge requests from GitHub context
- OSDU Targeting: Specialized support for community.opengroup.org GitLab instance
Learn about cross-platform AI

AI-Enhanced Extensions

These workflows extend the core fork management system with AI-powered capabilities that bridge platforms and enhance developer productivity. They operate alongside the core workflows without disrupting the fundamental three-branch strategy.

Workflow Event Architecture

Event-Driven Triggers

graph LR
    A[Schedule Events] --> B[Workflow Triggers]
    C[Repository Events] --> B
    D[Manual Events] --> B

    B --> E[Sync Workflows]
    B --> F[Validation Workflows]
    B --> G[Build Workflows]
    B --> H[Cascade Workflows]

    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style C fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style D fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

Trigger Type	Workflow	Schedule/Event	Description
Scheduled	Daily Sync	`0 0 * * *`	Midnight UTC upstream synchronization with duplicate prevention
Scheduled	Template Sync	`0 8 * * 1`	Monday 8 AM UTC template updates
Scheduled	Monitoring	`0 /6 * *`	6-hour cascade monitoring
Event-Based	PR Validation	PR creation/updates	Validation workflows on pull requests
Event-Based	Cascade Trigger	Issue creation	Cascade triggering on sync completion
Event-Based	Build	Push to main	Build workflows on main branch updates
Event-Based	Release	Tag creation	Distribution workflows on releases
AI-Triggered	GitLab Integration	`@alfi` mentions	Cross-platform GitLab MR creation from GitHub
Manual	Emergency Sync	On-demand	Immediate upstream synchronization
Manual	Cascade Override	On-demand	Manual cascade operation initiation
Manual	Template Update	On-demand	Immediate template propagation
Manual	Validation Retry	On-demand	Re-execution of failed workflows

Workflow Integration Patterns

AI-Enhanced Automation

Claude (Anthropic)

Primary AI provider for analysis and generation with comprehensive reasoning capabilities
Azure OpenAI

Enterprise alternative with Microsoft integration and compliance features
OpenAI GPT-4

Fallback option providing comprehensive coverage and established performance baselines

AI-Powered Capabilities enhance every stage of the workflow system:

Change Analysis: Intelligent assessment of upstream modifications
Commit Generation: Conventional commit message creation
PR Descriptions: Comprehensive pull request documentation
Conflict Guidance: Step-by-step conflict resolution instructions

Security Integration

Security-First Approach

All workflows integrate comprehensive security scanning and branch protection to ensure production stability and compliance.

Automated Security Scanning
- Trivy scanning for container and dependency vulnerabilities
- Secret detection and automated leak prevention
- GitHub security advisory integration
- Automated compliance rule validation
Branch Protection Integration
- Required workflow completion before merge
- Mandatory human approval for production changes
- Prevention of unauthorized direct pushes
- Controlled override procedures for critical issues

Workflow State Management

Issue-Based Tracking

Lifecycle Management

State Tracking: GitHub Issues for workflow state management
Progress Updates: Automated status updates throughout workflow execution
Error Reporting: Detailed failure analysis and resolution guidance
Audit Trail: Complete record of all workflow operations

Label-Based Organization

Workflow Types: upstream-sync, cascade-active, template-update
Status Indicators: in-progress, completed, requires-attention
Priority Levels: high-priority, critical, routine
Assignment Strategy: human-required for manual intervention points

Performance Optimization

Intelligent Caching
- Maven dependencies, Node modules, Docker layers
- Compiled assets and test results
- Upstream repository metadata
- Previously generated AI analysis results
Resource Management
- Concurrent workflow execution where safe
- Intelligent scheduling to prevent resource contention
- Appropriate timeouts with graceful degradation
- Exponential backoff for transient failures