workflow-templates-broken-zap-2026-06-08/docs/cicd

CI/CD System Overview

Package Architecture

hanzo-studio-workflow-templates/           # Meta package (depends on all others)
├── hanzo-studio-workflow-templates-core   # Manifest + core logic
├── hanzo-studio-workflow-templates-media-api     # API templates
├── hanzo-studio-workflow-templates-media-video   # Video templates  
├── hanzo-studio-workflow-templates-media-image   # Image templates
├── hanzo-studio-workflow-templates-media-other   # Other templates
└── hanzo-studio-subgraph-blueprints              # Subgraph blueprints

Workflow Pipeline

Template Added → Version Check → Package Bump → Publish → PyPI + GitHub Release

1. Template Addition (PR)

• Add template files to templates/
• MUST add template IDs to appropriate bundle in bundles.json
• CI auto-bumps affected package versions + updates meta dependencies

2. Version Detection (ci_version_manager.py)

• Analyzes git history since last package tag
• Bumps packages with template changes
• Updates meta package dependencies (exact pinning ==x.y.z)

3. Publishing (publish.yml)

• Triggers on pyproject.toml changes (main branch)
• Builds packages in dependency order (subpackages → meta)
• Recovery mode: publishes any packages newer than PyPI

Critical Files

• bundles.json - Template→package mapping (REQUIRED for new templates)
• pyproject.toml - Meta package with exact dependencies
• packages/*/pyproject.toml - Individual package versions
• Template manifests auto-generated by sync_bundles.py

Key Scripts

Core Logic

• scripts/ci_version_manager.py - Version detection/bumping logic
• scripts/sync_bundles.py - Template validation + manifest generation
• scripts/validate_manifests.py - SHA256 + file consistency checks
• scripts/sync_custom_nodes.py - Auto-populate requiresCustomNodes from workflow JSON
• scripts/validate_thumbnails.py - Thumbnail presence and variant validation
• scripts/check_input_assets.py - Input asset validation

CI Utilities

• scripts/ci/validate_bundles.sh - Bundle assignment validation (shared)
• scripts/ci/get_pypi_version.sh - Robust PyPI version fetching (shared)
• scripts/ci/get_version.sh - Consistent pyproject.toml version extraction (shared)

Validation Rules

• All templates in templates/*.json MUST be assigned in bundles.json
• Template assets MUST match manifest SHA256 hashes
• Package versions MUST use semantic versioning
• Meta dependencies MUST use exact pinning (==x.y.z)