Skip to content

GitHub Workflows Architecture

Detailed documentation of all GitHub Actions workflows and their interactions.

Workflow Overview

The project uses a sophisticated CI/CD pipeline with five interconnected workflows that handle testing, security, releases, and documentation deployment.

Complete Workflow Interaction Diagram

flowchart TD
    %% External Triggers
    Developer[👨‍💻 Developer] --> CodeChanges[📝 Code Changes]
    CodeChanges --> FeatureBranch[🌿 Feature Branch]
    FeatureBranch --> PullRequest[🔄 Pull Request to Main]

    %% PR Workflows
    PullRequest --> CI_PR[🚀 CI Workflow
Pull Request Trigger]
    PullRequest --> DepReview[🔍 Dependency Review
Security Analysis]

    %% CI PR Jobs
    CI_PR --> TestJob[🧪 Test Job
Matrix: Python 3.11, 3.12]
    CI_PR --> SecurityJob[🛡️ Security Job
Safety + Bandit]

    TestJob --> UnitTests[⚡ Unit Tests
Fast execution]
    TestJob --> IntegrationTests[🔗 Integration Tests
Component interaction]
    SecurityJob --> VulnerabilityCheck[🚨 Vulnerability Scan]
    SecurityJob --> CodeAnalysis[📊 Static Code Analysis]

    %% Dependency Review
    DepReview --> LicenseCheck[📄 License Compliance]
    DepReview --> SecurityAdvisory[🛡️ Security Advisory Check]

    %% PR Resolution
    UnitTests --> PRApproval{📋 PR Approval}
    IntegrationTests --> PRApproval
    VulnerabilityCheck --> PRApproval
    CodeAnalysis --> PRApproval
    LicenseCheck --> PRApproval
    SecurityAdvisory --> PRApproval

    PRApproval -->|✅ Approved| MergeToMain[🎯 Merge to Main]
    PRApproval -->|❌ Changes Needed| CodeChanges

    %% Main Branch Workflows
    MergeToMain --> CI_Main[🚀 CI Workflow
Main Branch Trigger]
    MergeToMain --> ReleasePleaseWorkflow[🎁 Release Please
Conventional Commit Analysis]
    MergeToMain --> DocsCheck{📚 Documentation
Changes?}

    %% CI Main Branch
    CI_Main --> MainTestJob[🧪 Full Test Suite
All Tests]
    CI_Main --> APITestJob[🌐 API Test Job
OpenAI Integration]
    CI_Main --> MainSecurityJob[🛡️ Security Validation]

    MainTestJob --> TestResults{✅ All Tests Pass?}
    APITestJob --> TestResults
    MainSecurityJob --> TestResults

    TestResults -->|❌ Failed| NotifyFailure[📧 Failure Notification
GitHub Checks Failed]
    TestResults -->|✅ Passed| CISuccess[✅ CI Success
Main Branch Validated]

    %% Release Please Logic
    ReleasePleaseWorkflow --> ConventionalCommitCheck{📝 Conventional
Commits Found?}
    ConventionalCommitCheck -->|❌ No| NoReleaseAction[❌ No Release Action
Wait for Next Push]
    ConventionalCommitCheck -->|✅ Yes| AnalyzeCommits[🔍 Analyze Commit Types
feat, fix, docs, etc.]

    AnalyzeCommits --> VersionBump[📈 Calculate Version Bump
Major/Minor/Patch]
    VersionBump --> GenerateChangelog[📋 Generate Changelog
From Commit Messages]
    GenerateChangelog --> CreateReleasePR[🔄 Create Release PR
Version + Changelog]

    CreateReleasePR --> ReleasePRReview{👀 Release PR
Review & Merge}
    ReleasePRReview -->|⏳ Pending| WaitForApproval[⏳ Wait for Manual
PR Approval]
    ReleasePRReview -->|✅ Merged| CreateGitTag[🏷️ Create Git Tag
Trigger Release]

    %% Release Workflow
    CreateGitTag --> ReleaseWorkflow[🚢 Release Workflow
Tag Push Trigger]
    ReleaseWorkflow --> ReleaseDetermine[🎯 Determine Release Type
Tag vs Manual]

    ReleaseDetermine --> ReleaseBuild[🏗️ Build Package
uv build]
    ReleaseDetermine --> ReleaseTest[🧪 Release Tests
Final Validation]

    ReleaseBuild --> PackageVerify[✅ Package Verification
twine check]
    ReleaseTest --> PackageVerify

    PackageVerify --> PublishCondition{🎯 Publish Ready?}
    PublishCondition -->|❌ Failed| ReleaseFailed[❌ Release Failed
Error Notification]
    PublishCondition -->|✅ Success| PyPIPublish[📦 Publish to PyPI
Package Distribution]

    PyPIPublish --> GitHubRelease[📋 Create GitHub Release
Release Notes + Assets]
    GitHubRelease --> TriggerVersionedDocs[📚 Trigger Versioned Docs
Repository Dispatch]
    TriggerVersionedDocs --> ReleaseComplete[✅ Release Complete
All Artifacts Published]

    %% Documentation Workflows
    DocsCheck -->|✅ Yes| DocsVersionedWorkflow[📚 Docs Versioned Workflow
Documentation Changes]
    DocsCheck -->|❌ No| CISuccess

    DocsVersionedWorkflow --> DetermineDocsType[🎯 Determine Deployment Type
Latest vs Versioned]

    DetermineDocsType -->|📄 Latest| DeployLatest[🌐 Deploy Latest Docs
GitHub Pages Root]
    DetermineDocsType -->|🏷️ Versioned| DeployVersioned[📋 Deploy Versioned Docs
Version-specific Path]

    DeployLatest --> MikeDeploy1[⚙️ Mike Deploy Latest
Preserve Existing Versions]
    DeployVersioned --> MikeDeploy2[⚙️ Mike Deploy Version
Add New Version]

    MikeDeploy1 --> UpdateVersionSelector1[🔄 Update Version Selector
Latest as Default]
    MikeDeploy2 --> UpdateVersionSelector2[🔄 Update Version Selector
Add New Version]

    UpdateVersionSelector1 --> DocsSuccess[✅ Documentation Deployed
GitHub Pages Updated]
    UpdateVersionSelector2 --> DocsSuccess

    %% Repository Dispatch from Release
    TriggerVersionedDocs --> DispatchEvent[📡 Repository Dispatch
release-triggered Event]
    DispatchEvent --> DocsVersionedWorkflow

    %% Styling
    classDef devStyle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef ciStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef releaseStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef docsStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef decisionStyle fill:#fafafa,stroke:#424242,stroke-width:2px

    class Developer,CodeChanges,FeatureBranch devStyle
    class CI_PR,CI_Main,TestJob,SecurityJob,MainTestJob,APITestJob,MainSecurityJob ciStyle
    class ReleasePleaseWorkflow,ReleaseWorkflow,ReleaseBuild,PyPIPublish,GitHubRelease releaseStyle
    class DocsVersionedWorkflow,DeployLatest,DeployVersioned,MikeDeploy1,MikeDeploy2 docsStyle
    class ReleaseFailed,NotifyFailure errorStyle
    class CISuccess,ReleaseComplete,DocsSuccess successStyle
    class PRApproval,TestResults,ConventionalCommitCheck,ReleasePRReview,PublishCondition,DocsCheck,DetermineDocsType decisionStyle

Individual Workflow Details

1. CI Workflow (ci.yml)

flowchart TD
    %% Triggers
    PRTrigger[📥 Pull Request
to main/develop] --> CIStart[🚀 CI Workflow Start]
    PushTrigger[📥 Push to
main branch] --> CIStart
    ManualTrigger[📥 Manual
Workflow Dispatch] --> CIStart

    %% Job Matrix Setup
    CIStart --> SetupMatrix[⚙️ Setup Test Matrix
Python 3.11 & 3.12
Ubuntu Latest]

    %% Test Job
    SetupMatrix --> TestJob[🧪 Test Job
Matrix Strategy]
    TestJob --> InstallUV[📦 Install UV
Package Manager]
    InstallUV --> SyncDeps[🔄 Sync Dependencies
uv sync]
    SyncDeps --> LintFormat[🧹 Lint & Format
ruff check & format]
    LintFormat --> RunTests[⚡ Run Tests
pytest with markers]

    RunTests --> UnitTests[🔬 Unit Tests
@pytest.mark.unit]
    RunTests --> IntegrationTests[🔗 Integration Tests
@pytest.mark.integration]
    RunTests --> EdgeCaseTests[⚠️ Edge Case Tests
@pytest.mark.edge_case]

    UnitTests --> TestResults{✅ Test Results}
    IntegrationTests --> TestResults
    EdgeCaseTests --> TestResults

    %% API Tests (Conditional)
    TestResults -->|✅ Passed| APICheck{🌐 API Tests
Required?}
    TestResults -->|❌ Failed| TestFailed[❌ CI Failed
Test Failures]

    APICheck -->|Main Branch or [api-test]| APITestJob[🌐 API Test Job
OpenAI Integration]
    APICheck -->|Other Branches| SkipAPI[⏭️ Skip API Tests
Branch Protection]

    APITestJob --> APIKeyCheck[🔑 API Key Validation
Test Environment Detection]
    APIKeyCheck --> RunAPITests[🤖 Run API Tests
@pytest.mark.api]
    RunAPITests --> APIResults{✅ API Results}

    APIResults -->|✅ Passed| SecurityJob[🛡️ Security Job]
    APIResults -->|❌ Failed| APIFailed[❌ API Tests Failed
Integration Issues]
    SkipAPI --> SecurityJob

    %% Security Job
    SecurityJob --> InstallSecTools[🛡️ Install Security Tools
safety, bandit]
    InstallSecTools --> VulnScan[🚨 Vulnerability Scan
safety scan]
    VulnScan --> StaticAnalysis[📊 Static Analysis
bandit -r src/]

    StaticAnalysis --> SecurityResults{🛡️ Security Results}
    SecurityResults -->|✅ Passed| CISuccess[✅ CI Success
All Checks Passed]
    SecurityResults -->|❌ Failed| SecurityFailed[❌ Security Failed
Vulnerabilities Found]

    %% Final States
    TestFailed --> CIFailed[❌ CI Pipeline Failed]
    APIFailed --> CIFailed
    SecurityFailed --> CIFailed
    CISuccess --> NextWorkflow[➡️ Trigger Next Workflow
If Main Branch]

    %% Styling
    classDef triggerStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef jobStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef testStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef securityStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px

    class PRTrigger,PushTrigger,ManualTrigger triggerStyle
    class TestJob,APITestJob,SecurityJob jobStyle
    class UnitTests,IntegrationTests,EdgeCaseTests,RunAPITests testStyle
    class VulnScan,StaticAnalysis,APIKeyCheck securityStyle
    class CISuccess,NextWorkflow successStyle
    class TestFailed,APIFailed,SecurityFailed,CIFailed errorStyle

2. Release Please Workflow (release-please.yml)

flowchart TD
    %% Trigger
    PushMain[📥 Push to Main
Branch] --> RPStart[🎁 Release Please
Workflow Start]

    %% Initial Checks
    RPStart --> CheckCommits[🔍 Check Recent Commits
Last 10 commits]
    CheckCommits --> ConventionalCheck{📝 Conventional
Commits Found?}

    ConventionalCheck -->|❌ No| LogNoAction[📝 Log: No Action
No conventional commits]
    ConventionalCheck -->|✅ Yes| ShowCommits[📋 Show Found Commits
feat, fix, docs, etc.]

    %% Release Please Action
    ShowCommits --> ReleasePleaseAction[🚀 Release Please Action
googleapis/release-please-action@v4]
    ReleasePleaseAction --> AnalyzeCommits[🔍 Analyze Commit Types
Determine Version Bump]

    AnalyzeCommits --> VersionCalculation{📈 Version Calculation}
    VersionCalculation -->|feat| MinorBump[📈 Minor Version Bump
New Feature]
    VersionCalculation -->|fix| PatchBump[🔧 Patch Version Bump
Bug Fix]
    VersionCalculation -->|BREAKING| MajorBump[💥 Major Version Bump
Breaking Change]
    VersionCalculation -->|docs,chore| NoBump[📝 No Version Bump
Documentation Only]

    %% Generate Changelog
    MinorBump --> GenerateChangelog[📋 Generate Changelog
From Commit Messages]
    PatchBump --> GenerateChangelog
    MajorBump --> GenerateChangelog

    GenerateChangelog --> CheckExistingPR{🔄 Existing
Release PR?}
    CheckExistingPR -->|✅ Yes| UpdatePR[🔄 Update Existing PR
New Commits + Changelog]
    CheckExistingPR -->|❌ No| CreatePR[🆕 Create New Release PR
Version Bump + Changelog]

    %% PR Management
    UpdatePR --> PRReady[📋 Release PR Ready
For Review & Merge]
    CreatePR --> PRReady

    PRReady --> WaitForMerge[⏳ Wait for Manual
PR Review & Merge]
    WaitForMerge --> PRMerged{✅ PR Merged?}

    PRMerged -->|❌ Not Yet| WaitForMerge
    PRMerged -->|✅ Merged| CreateTag[🏷️ Create Git Tag
Trigger Release Workflow]

    %% Tag Creation
    CreateTag --> TagDetails[📋 Tag Details
Version + Release Notes]
    TagDetails --> TriggerRelease[🚢 Trigger Release Workflow
Tag Push Event]

    %% No Action Paths
    NoBump --> LogNoAction
    LogNoAction --> WorkflowComplete[✅ Workflow Complete
No Release Action]

    %% Debug Output
    ReleasePleaseAction --> DebugOutput[🔍 Debug Output
Release Created, Tag Name, PR Details]
    DebugOutput --> CheckManifest[📋 Check Manifest File
.release-please-manifest.json]
    CheckManifest --> VersionCalculation

    %% Final States
    TriggerRelease --> RPSuccess[✅ Release Please Success
Tag Created, Release Triggered]
    WorkflowComplete --> RPComplete[✅ Workflow Complete
No Changes Needed]

    %% Styling
    classDef triggerStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef processStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef versionStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef prStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef debugStyle fill:#f5f5f5,stroke:#757575,stroke-width:2px

    class PushMain triggerStyle
    class RPStart,CheckCommits,AnalyzeCommits,GenerateChangelog processStyle
    class MinorBump,PatchBump,MajorBump,NoBump versionStyle
    class UpdatePR,CreatePR,PRReady,WaitForMerge prStyle
    class RPSuccess,RPComplete,WorkflowComplete successStyle
    class DebugOutput,CheckManifest debugStyle

3. Release Workflow (release.yml)

flowchart TD
    %% Triggers
    TagPush[📥 Git Tag Push
v*.*.* pattern] --> ReleaseStart[🚢 Release Workflow
Start]
    ManualDispatch[📥 Manual Dispatch
version input] --> ReleaseStart

    %% Release Please Integration
    ReleasePleaseTag[🏷️ Tag from
Release Please] --> TagPush

    %% Job Setup
    ReleaseStart --> DetermineType[🎯 Determine Release Type
Tag Push vs Manual]
    DetermineType --> DebugContext[🔍 Debug Workflow Context
Event, Ref, Secrets Check]

    DebugContext --> ReleaseJob[🚢 Release Job
Ubuntu Latest]

    %% Build Process
    ReleaseJob --> CheckoutCode[📥 Checkout Repository
Full History]
    CheckoutCode --> InstallUV[📦 Install UV Package Manager
Latest Version]
    InstallUV --> SetupPython[🐍 Setup Python 3.12
uv python install]
    SetupPython --> SyncDeps[🔄 Install Dependencies
uv sync]

    %% Testing Phase
    SyncDeps --> RunTests[🧪 Run Full Test Suite
All Test Markers]
    RunTests --> TestResults{✅ Tests Pass?}

    TestResults -->|❌ Failed| TestsFailed[❌ Release Failed
Tests Not Passing]
    TestResults -->|✅ Passed| BuildPackage[🏗️ Build Python Package
uv build]

    %% Package Verification
    BuildPackage --> InstallTwine[📦 Install Twine
Package Verification]
    InstallTwine --> VerifyPackage[✅ Verify Package
twine check dist/*]

    VerifyPackage --> VerificationResult{✅ Package Valid?}
    VerificationResult -->|❌ Failed| PackageFailed[❌ Release Failed
Package Verification Error]
    VerificationResult -->|✅ Passed| CheckSecrets[🔑 Check PyPI Secrets
PYPI_API_TOKEN exists]

    %% Publishing Phase
    CheckSecrets --> SecretCheck{🔐 Secrets Available?}
    SecretCheck -->|❌ Missing| SecretsMissing[❌ Release Failed
Missing PyPI Token]
    SecretCheck -->|✅ Available| PublishPyPI[📦 Publish to PyPI
twine upload]

    PublishPyPI --> PublishResult{📦 Publish Success?}
    PublishResult -->|❌ Failed| PublishFailed[❌ PyPI Publish Failed
Upload Error]
    PublishResult -->|✅ Success| CreateRelease[📋 Create GitHub Release
Tag + Release Notes]

    %% GitHub Release Creation
    CreateRelease --> AttachAssets[📎 Attach Build Artifacts
dist/* files]
    AttachAssets --> ReleaseResult{📋 Release Created?}

    ReleaseResult -->|❌ Failed| ReleaseFailed[❌ GitHub Release Failed
API Error]
    ReleaseResult -->|✅ Success| TriggerDocs[📚 Trigger Documentation
Repository Dispatch]

    %% Documentation Trigger
    TriggerDocs --> DocsDispatch[📡 Send Repository Dispatch
release-triggered Event]
    DocsDispatch --> DocsResult{📡 Dispatch Success?}

    DocsResult -->|❌ Failed| DocsDispatchFailed[⚠️ Docs Dispatch Failed
Manual Trigger Needed]
    DocsResult -->|✅ Success| ReleaseSuccess[✅ Release Complete
All Systems Updated]

    %% Error Handling
    TestsFailed --> NotifyFailure[📧 Notify Failure
GitHub Status Check]
    PackageFailed --> NotifyFailure
    SecretsMissing --> NotifyFailure
    PublishFailed --> NotifyFailure
    ReleaseFailed --> NotifyFailure
    DocsDispatchFailed --> PartialSuccess[⚠️ Partial Success
Package Released, Docs Manual]

    %% Final States
    NotifyFailure --> WorkflowFailed[❌ Release Workflow Failed]
    PartialSuccess --> WorkflowPartial[⚠️ Release Partially Complete]
    ReleaseSuccess --> WorkflowSuccess[✅ Release Workflow Success]

    %% Styling
    classDef triggerStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef processStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef testStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef buildStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef publishStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px
    classDef warningStyle fill:#fffde7,stroke:#f9a825,stroke-width:2px

    class TagPush,ManualDispatch,ReleasePleaseTag triggerStyle
    class ReleaseStart,DetermineType,DebugContext,ReleaseJob processStyle
    class RunTests,TestResults testStyle
    class BuildPackage,InstallTwine,VerifyPackage buildStyle
    class PublishPyPI,CreateRelease,AttachAssets publishStyle
    class ReleaseSuccess,WorkflowSuccess successStyle
    class TestsFailed,PackageFailed,PublishFailed,ReleaseFailed,WorkflowFailed errorStyle
    class PartialSuccess,WorkflowPartial,DocsDispatchFailed warningStyle

4. Documentation Versioned Workflow (docs-versioned.yml)

Enhanced Trigger Logic & Safety Checks

The docs-versioned workflow has been significantly improved with robust trigger logic and comprehensive safety checks:

Key Improvements:

  • Enhanced Trigger Logic: Proper handling of all event types (push, release, repository_dispatch, workflow_dispatch)
  • Version Validation: Validates semantic version format before deployment
  • Conflict Resolution: Retry logic with exponential backoff for concurrent deployments
  • Safety Checks: Prevents no-op deployments with explicit verification
  • Comprehensive Logging: Debug output for troubleshooting deployment issues
flowchart TD
    %% Triggers with Enhanced Logic
    PushMain[📥 Push to Main
docs/** changes] --> DocsStart[📚 Docs Versioned
Workflow Start]
    ReleaseCreated[📥 Release Created
published event] --> DocsStart
    RepoDispatch[📥 Repository Dispatch
release-triggered] --> DocsStart
    ManualDispatch[📥 Manual Dispatch
version input] --> DocsStart

    %% Enhanced Deployment Type Determination
    DocsStart --> ConcurrencyCheck[🔄 Concurrency Control
docs-deployment-gh-pages]
    ConcurrencyCheck --> DetermineType[🎯 Enhanced Deployment Logic
Comprehensive Event Analysis]

    %% Improved Decision Logic
    DetermineType --> TriggerAnalysis{🔍 Trigger Analysis}
    TriggerAnalysis -->|Push to Main| DeployLatest[📄 Deploy Latest
Documentation Changes]
    TriggerAnalysis -->|Release Event| ExtractReleaseVersion[📋 Extract Release Version
From release.tag_name]
    TriggerAnalysis -->|Repository Dispatch| ExtractDispatchVersion[📋 Extract Dispatch Version
From client_payload.tag]
    TriggerAnalysis -->|Manual Latest| DeployLatest
    TriggerAnalysis -->|Manual Version| ExtractManualVersion[📋 Extract Manual Version
From inputs.version]

    %% Version Processing
    ExtractReleaseVersion --> ValidateVersion[✅ Validate Version Format
Semantic Versioning Check]
    ExtractDispatchVersion --> ValidateVersion
    ExtractManualVersion --> ValidateVersion

    ValidateVersion --> VersionCheck{📋 Version Valid?}
    VersionCheck -->|❌ Invalid| ValidationFailed[❌ Version Validation Failed
Invalid Format]
    VersionCheck -->|✅ Valid| DeployVersioned[🏷️ Deploy Versioned Docs
New Version Release]

    %% Safety Check Job
    DetermineType --> SafetyCheck[🛡️ Safety Check Job
Prevent No-Op Deployments]
    SafetyCheck --> ShouldDeploy{🤔 Should Deploy?}
    ShouldDeploy -->|❌ No| WarnNoDeployment[⚠️ Warn No Deployment
Event Type Not Handled]
    ShouldDeploy -->|✅ Yes| ProceedDeployment[✅ Proceed with Deployment
Event Matches Trigger Logic]

    %% Latest Documentation Deployment
    DeployLatest --> LatestSetup[⚙️ Setup Latest Environment
UV + Python 3.12]
    LatestSetup --> LatestSync[🔄 Sync Dependencies
uv sync]
    LatestSync --> LatestGitConfig[⚙️ Configure Git
GitHub Action credentials]

    LatestGitConfig --> FetchGHPages1[📡 Fetch gh-pages Branch
Conflict Prevention]
    FetchGHPages1 --> MikeLatestLocal[📚 Mike Deploy Latest Local
update-aliases + set-default]

    %% Enhanced Retry Logic for Latest
    MikeLatestLocal --> LatestRetryLoop[🔄 Enhanced Retry Loop
Max 3 Attempts, Exponential Backoff]
    LatestRetryLoop --> LatestPushAttempt[📤 Latest Push Attempt
git push origin gh-pages]
    LatestPushAttempt --> LatestPushResult{📤 Push Success?}

    LatestPushResult -->|✅ Success| LatestComplete[✅ Latest Docs Deployed
Default Version Updated]
    LatestPushResult -->|❌ Failed| LatestConflictResolve[🔄 Resolve Latest Conflicts
Rebase + Re-deploy]
    LatestConflictResolve --> MikeLatestLocal

    %% Versioned Documentation Deployment
    DeployVersioned --> VersionedSetup[⚙️ Setup Versioned Environment
UV + Python 3.12]
    VersionedSetup --> VersionedSync[🔄 Sync Dependencies
uv sync]
    VersionedSync --> VersionedGitConfig[⚙️ Configure Git
GitHub Action credentials]

    VersionedGitConfig --> FetchGHPages2[📡 Fetch gh-pages Branch
Conflict Prevention]
    FetchGHPages2 --> MikeVersionedLocal[📚 Mike Deploy Version Local
update-aliases for vX.Y.Z]

    %% Enhanced Retry Logic for Versioned
    MikeVersionedLocal --> VersionedRetryLoop[🔄 Enhanced Retry Loop
Max 3 Attempts, Exponential Backoff]
    VersionedRetryLoop --> VersionedPushAttempt[📤 Versioned Push Attempt
git push origin gh-pages]
    VersionedPushAttempt --> VersionedPushResult{📤 Push Success?}

    VersionedPushResult -->|✅ Success| VersionedComplete[✅ Versioned Docs Deployed
New Version Available]
    VersionedPushResult -->|❌ Failed| VersionedConflictResolve[🔄 Resolve Version Conflicts
Rebase + Re-deploy]
    VersionedConflictResolve --> MikeVersionedLocal

    %% Comprehensive Error Handling
    LatestSetup --> LatestError{❌ Setup Error?}
    VersionedSetup --> VersionedError{❌ Setup Error?}

    LatestError -->|✅ Success| LatestSync
    LatestError -->|❌ Failed| LatestFailed[❌ Latest Deploy Failed
Environment Setup Error]

    VersionedError -->|✅ Success| VersionedSync
    VersionedError -->|❌ Failed| VersionedFailed[❌ Versioned Deploy Failed
Environment Setup Error]

    %% Final Success States
    LatestComplete --> LogLatestSuccess[📝 Log Latest Success
GitHub Pages Updated]
    VersionedComplete --> LogVersionedSuccess[📝 Log Versioned Success
Version URL Available]

    LogLatestSuccess --> DocsSuccess[✅ Documentation Workflow Complete
All Systems Updated]
    LogVersionedSuccess --> DocsSuccess

    %% Final Error States
    ValidationFailed --> DocsFailed[❌ Documentation Workflow Failed]
    WarnNoDeployment --> DocsSkipped[⏭️ Documentation Workflow Skipped]
    LatestFailed --> DocsFailed
    VersionedFailed --> DocsFailed

    %% Integration Points
    DocsSuccess --> UpdateGitHubPages[🌐 GitHub Pages Updated
Documentation Live]
    UpdateGitHubPages --> VersionSelectorUpdate[🔄 Version Selector Updated
Mike Built-in Functionality]

    %% Styling
    classDef triggerStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef processStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef deployStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef mikeStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef validationStyle fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px
    classDef retryStyle fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px
    classDef warningStyle fill:#fffde7,stroke:#f9a825,stroke-width:2px
    classDef skipStyle fill:#f5f5f5,stroke:#757575,stroke-width:2px

    class PushMain,ReleaseCreated,RepoDispatch,ManualDispatch triggerStyle
    class DocsStart,ConcurrencyCheck,DetermineType,TriggerAnalysis,SafetyCheck processStyle
    class DeployLatest,DeployVersioned,LatestSetup,VersionedSetup deployStyle
    class MikeLatestLocal,MikeVersionedLocal mikeStyle
    class ValidateVersion,VersionCheck,ExtractReleaseVersion,ExtractDispatchVersion,ExtractManualVersion validationStyle
    class LatestRetryLoop,VersionedRetryLoop,LatestConflictResolve,VersionedConflictResolve retryStyle
    class DocsSuccess,LatestComplete,VersionedComplete,UpdateGitHubPages,VersionSelectorUpdate successStyle
    class ValidationFailed,LatestFailed,VersionedFailed,DocsFailed errorStyle
    class WarnNoDeployment warningStyle
    class DocsSkipped skipStyle

Key Workflow Features

Enhanced Trigger Logic:

  • Push to Main: Automatically deploys latest documentation for docs changes
  • Release Events: Extracts version from release.tag_name and deploys versioned docs
  • Repository Dispatch: Handles release-triggered events from release workflow
  • Manual Dispatch: Supports both "latest" and specific version deployments

Version Validation:

  • Validates semantic versioning format (X.Y.Z or X.Y.Z-suffix)
  • Prevents deployment of invalid version formats
  • Comprehensive error reporting for validation failures

Conflict Resolution:

  • Robust retry logic with exponential backoff (3 attempts)
  • Automatic conflict resolution via rebase/reset
  • Prevents concurrent deployment conflicts with exclusive concurrency group

Safety & Monitoring:

  • Explicit no-deployment warnings for unhandled events
  • Comprehensive debug logging throughout the process
  • Clear success/failure reporting with actionable URLs

5. Dependency Review Workflow (dependency-review.yml)

flowchart TD
    %% Trigger
    PRCreated[📥 Pull Request
to main/develop] --> DepStart[🔍 Dependency Review
Workflow Start]

    %% Setup
    DepStart --> CheckoutPR[📥 Checkout PR
Compare Changes]
    CheckoutPR --> DepReviewAction[🔍 Dependency Review Action
github/dependency-review-action]

    %% Configuration Loading
    DepReviewAction --> LoadConfig[⚙️ Load Configuration
dependency-review-config.yml]
    LoadConfig --> ConfigDetails[📋 Configuration Details
Severity: moderate
Licenses: MIT, Apache-2.0, BSD
Scopes: runtime]

    %% Vulnerability Analysis
    ConfigDetails --> VulnAnalysis[🚨 Vulnerability Analysis
Compare PR dependencies]
    VulnAnalysis --> SecurityAdvisory[🛡️ Check Security Advisories
GitHub Advisory Database]

    SecurityAdvisory --> VulnResults{🚨 Vulnerabilities
Found?}
    VulnResults -->|✅ None| LicenseCheck[📄 License Compliance Check
Allowed licenses only]
    VulnResults -->|⚠️ Low/Info| VulnWarning[⚠️ Vulnerability Warning
Low severity found]
    VulnResults -->|❌ Moderate+| VulnFailed[❌ Vulnerability Failure
Blocked by security]

    %% License Checking
    VulnWarning --> LicenseCheck
    LicenseCheck --> LicenseResults{📄 License
Compliance?}

    LicenseResults -->|✅ Compliant| ScopeCheck[🎯 Scope Analysis
Runtime dependencies]
    LicenseResults -->|❌ Non-compliant| LicenseFailed[❌ License Failure
Incompatible license found]

    %% Scope Analysis
    ScopeCheck --> ScopeResults{🎯 Scope
Analysis?}
    ScopeResults -->|✅ Runtime OK| GenerateReport[📋 Generate Report
Dependency summary]
    ScopeResults -->|⚠️ Dev Dependencies| ScopeWarning[⚠️ Development Dependencies
Non-runtime scope]

    %% Report Generation
    ScopeWarning --> GenerateReport
    GenerateReport --> LicenseReport[📄 License Report
All dependency licenses]
    LicenseReport --> SecurityReport[🛡️ Security Report
Vulnerability summary]

    %% Final Results
    SecurityReport --> ReviewSuccess[✅ Dependency Review Passed
All checks successful]

    %% Failure Paths
    VulnFailed --> BlockPR[🚫 Block PR Merge
Security vulnerability]
    LicenseFailed --> BlockPR
    BlockPR --> NotifyFailure[📧 Notify PR Author
Dependency issues found]

    %% Success Path
    ReviewSuccess --> AllowMerge[✅ Allow PR Merge
Dependencies approved]
    AllowMerge --> AddReviewComment[💬 Add Review Comment
Dependency summary]

    %% Final States
    NotifyFailure --> ReviewFailed[❌ Dependency Review Failed]
    AddReviewComment --> ReviewComplete[✅ Dependency Review Complete]

    %% Styling
    classDef triggerStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef processStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef securityStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef licenseStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef reportStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef successStyle fill:#e0f2f1,stroke:#00695c,stroke-width:2px
    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px
    classDef warningStyle fill:#fffde7,stroke:#f9a825,stroke-width:2px

    class PRCreated triggerStyle
    class DepStart,CheckoutPR,DepReviewAction,LoadConfig processStyle
    class VulnAnalysis,SecurityAdvisory,VulnResults securityStyle
    class LicenseCheck,LicenseResults licenseStyle
    class GenerateReport,LicenseReport,SecurityReport reportStyle
    class ReviewSuccess,AllowMerge,ReviewComplete successStyle
    class VulnFailed,LicenseFailed,BlockPR,ReviewFailed errorStyle
    class VulnWarning,ScopeWarning warningStyle

Workflow Integration Points

Secret Management

graph TB
    Secrets[🔐 GitHub Secrets] --> OpenAI[OPENAI_API_KEY
🤖 API Tests]
    Secrets --> PyPI[PYPI_API_TOKEN
📦 Package Publishing]
    Secrets --> Analytics[GOOGLE_ANALYTICS_KEY
📊 Docs Analytics]
    Secrets --> Safety[SAFETY_API_KEY
🛡️ Security Scanning]

    OpenAI --> CI[🚀 CI Workflow
API Tests]
    PyPI --> Release[🚢 Release Workflow
PyPI Publishing]
    Analytics --> Docs[📚 Documentation
Usage Tracking]
    Safety --> CI2[🚀 CI Workflow
Vulnerability Scanning]

    classDef secretStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef workflowStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px

    class Secrets secretStyle
    class CI,CI2,Release,Docs workflowStyle

Concurrency Control

graph LR
    ConcurrentPRs[Multiple PRs] --> CIQueue[CI Queue
Parallel Execution]
    MainPush[Main Branch Push] --> MainQueue[Main Branch Queue
Sequential Execution]
    ReleaseTag[Release Tag] --> ReleaseQueue[Release Queue
Exclusive Access]
    DocChanges[Docs Changes] --> DocsQueue[📚 Docs Deployment
docs-deployment-gh-pages
Sequential Only]

    CIQueue --> CIRuns[Multiple CI Runs
✅ Parallel OK]
    MainQueue --> MainRuns[Sequential Main Builds
⚡ One at a time]
    ReleaseQueue --> ReleaseRuns[Exclusive Release
🚢 No interference]
    DocsQueue --> DocsRuns[Sequential Docs Deploy
📚 Prevent conflicts]

    classDef concurrencyStyle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef executionStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px

    class ConcurrentPRs,MainPush,ReleaseTag,DocChanges concurrencyStyle
    class CIRuns,MainRuns,ReleaseRuns,DocsRuns executionStyle

Monitoring and Observability

Workflow Status Dashboard

The workflows provide comprehensive monitoring through:

  1. GitHub Actions Dashboard: Real-time workflow status
  2. Status Checks: PR blocking for failed workflows
  3. Notifications: Email/GitHub notifications for failures
  4. Debug Logging: Comprehensive debug output for troubleshooting
  5. Artifact Storage: Build artifacts and logs for analysis

Key Metrics to Monitor

  • CI Success Rate: Percentage of passing CI runs
  • Release Frequency: Number of releases per month
  • Documentation Deployment: Latest vs versioned deployment success
  • Security Scan Results: Vulnerability trends over time
  • Dependency Updates: License compliance and security updates

This architecture ensures robust, automated CI/CD with comprehensive error handling, security scanning, and documentation management.