Skip to main content
Version: 0.0.1

Reusable Workflows & Template Repository Architecture

Template Architecture External Workflows Centralized

The slack-mcp-server CI/CD system leverages a template repository architecture using reusable workflows from Chisanan232/Template-Python-UV-Project. This approach provides standardized, centrally-maintained workflows while promoting consistency, maintainability, and the DRY (Don't Repeat Yourself) principle across all template-based projects.

Template Project Resources

🏛️ Repository: Chisanan232/Template-Python-UV-Project
📖 Documentation: Template Project CI/CD Guide
⚙️ Workflows: /.github/workflows/
🔄 Reusable Workflows: Template Workflow Reference

💡 About the Template: A comprehensive collection of GitHub Actions workflows designed for Python UV projects, featuring standardized testing, coverage reporting, release management, and documentation deployment patterns.

Template Repository Architecture​

The project now uses a hybrid architecture combining local project-specific workflows with external template repository workflows:

🏠 Local Workflows (Project-Specific)​

☁️ Template Repository Workflows (Centralized & Maintained)​

Explore More Workflows

The template repository provides additional workflows for release management, Docker operations, and documentation deployment. See the complete workflow catalog

Architecture Benefits:​

  • ✅ Centralized Maintenance: Core testing workflows maintained in template repository
  • ✅ Automatic Updates: Bug fixes and improvements flow to all template-based projects
  • ✅ Local Customization: Project-specific orchestration and configuration
  • ✅ Consistency: Standardized testing patterns across template ecosystem
  • ✅ Reduced Duplication: Common workflows shared, not duplicated
  • ✅ Community Driven: Open-source template with active development and contributions
  • ✅ Comprehensive Documentation: Detailed guides and examples at Template Docs

Core Reusable Workflows​

1. Local Build and Test Orchestration (rw_build_and_test.yaml)​

Purpose: Local orchestration workflow that coordinates multiple test types using template repository workflows.

Template Repository Integration:

# Uses external template repository workflows
jobs:
  run_unit-test:
    uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml@master
    with:
      test_type: unit-test
      test_folder: './test/unit_test'
      python-versions: '["3.13"]'
      operating-systems: '["ubuntu-latest", "ubuntu-22.04", "macos-latest", "macos-14"]'

📋 Template Workflow: rw_uv_run_test_with_multi_py_versions.yaml

Key Features:

  • Template Integration: Uses centralized workflows from template repository
  • Test Orchestration: Coordinates unit, integration, contract, E2E, and CI script tests
  • Coverage Organization: Integrates with template repository coverage workflows
  • Hardcoded Configuration: Python 3.13 and 4 OS variants for comprehensive testing

2. External Multi-Python Testing (Template Repository)​

Source: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml@master

Purpose: Comprehensive testing across multiple Python versions and operating systems with UV toolchain.

Matrix Strategy:

uses: ./.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml
with:
  python-versions: '["3.9", "3.10", "3.11", "3.12"]'
  test-type: 'unit'  # or 'integration', 'e2e'

Key Features (Template Repository Provided):

  • Matrix Testing: Configurable Python versions and operating systems
  • UV Test Integration: Uses uv run for consistent test environments
  • Flexible Test Types: Supports unit, integration, E2E, and contract testing
  • Parameterized Configuration: Accepts custom Python versions and OS combinations

3. External Coverage Organization (Template Repository)​

Source: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_organize_test_cov_reports.yaml@master

Purpose: Standardized test coverage reporting and organization from template repository.

Integration Example:

jobs:
  unit-test_codecov:
    uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_organize_test_cov_reports.yaml@master
    with:
      test_type: unit-test

📋 Template Workflow: rw_organize_test_cov_reports.yaml

Key Features (Template Repository Provided):

  • Multi-Format Support: Generates coverage in XML, HTML, and JSON formats
  • Report Merging: Combines coverage from multiple test runs and OS variants
  • Artifact Organization: Structured storage and upload of coverage reports
  • Template Consistency: Standardized across all template-based projects

4. Local Test Coordination (rw_run_all_test_and_record.yaml)​

Purpose: Local coordination workflow that orchestrates the complete CI pipeline using template workflows.

Template Integration:

jobs:
  build-and-test:
    uses: ./.github/workflows/rw_build_and_test.yaml  # Local orchestrator
    with:
      run_e2e: ${{ inputs.run_e2e }}

Key Features:

  • Pipeline Orchestration: Coordinates build, test, and reporting phases
  • Codecov Integration: Uploads organized coverage reports to Codecov
  • SonarCloud Integration: Performs code quality analysis
  • Conditional E2E Testing: Optional end-to-end test execution

Template Repository Migration Benefits​

🚀 Migration Overview​

The project has successfully migrated from local reusable workflows to a template repository architecture. This migration provides significant benefits:

📦 Before: Local Workflows​

  • ❌ Duplicated workflow logic across projects
  • ❌ Manual maintenance of common testing patterns
  • ❌ Inconsistent implementations between projects
  • ❌ Individual bug fixes required per project

☁️ After: Template Repository Architecture​

  • ✅ Centralized workflow maintenance in template repository
  • ✅ Automatic propagation of improvements and bug fixes
  • ✅ Consistent testing patterns across all template-based projects
  • ✅ Local customization with global standardization

Current Architecture Pattern​

Template Repository Workflow Integration​

The current integration pattern leverages external template workflows:

jobs:
  # Local orchestration with template repository workflows
  run_unit-test:
    uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml@master
    with:
      test_type: unit-test
      test_folder: './test/unit_test'
      python-versions: '["3.13"]'
      operating-systems: '["ubuntu-latest", "ubuntu-22.04", "macos-latest", "macos-14"]'

  unit-test_codecov:
    uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_organize_test_cov_reports.yaml@master
    with:
      test_type: unit-test
Template Workflows Used

rw_uv_run_test_with_multi_py_versions.yaml • rw_organize_test_cov_reports.yaml

Multi-Python Testing Pattern​

CI workflows integrate multi-version testing for comprehensive compatibility validation:

jobs:
  # Main build and test
  build_and_test:
    uses: ./.github/workflows/rw_build_and_test.yaml
    with:
      python-version: '3.11'
  
  # Multi-Python version testing
  test_multi_versions:
    needs: [build_and_test]
    uses: ./.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml
    with:
      python-versions: '["3.9", "3.10", "3.11", "3.12"]'
      test-type: 'unit'
  
  # Comprehensive test execution
  run_all_tests:
    needs: [test_multi_versions]
    uses: ./.github/workflows/rw_run_all_test_and_record.yaml
    with:
      test-suite: 'all'
      record-artifacts: true
  
  # Coverage organization
  organize_coverage:
    needs: [run_all_tests]
    uses: ./.github/workflows/rw_organize_test_cov_reports.yaml
    with:
      coverage-format: 'xml'
      upload-codecov: true

Conditional Execution Patterns​

Reusable workflows support conditional execution based on triggers and configurations:

jobs:
  # Run comprehensive tests only on main branch
  comprehensive_tests:
    if: github.ref == 'refs/heads/main'
    uses: ./.github/workflows/rw_run_all_test_and_record.yaml
    with:
      test-suite: 'all'
      record-artifacts: true
  
  # Run quick tests on feature branches
  quick_tests:
    if: github.ref != 'refs/heads/main'
    uses: ./.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml
    with:
      python-versions: '["3.11"]'
      test-type: 'unit'

Architecture Benefits​

DRY Principle Implementation​

Before Reusable Workflows:

  • Python build and test logic duplicated across multiple workflows
  • Inconsistent test execution patterns
  • Divergent coverage reporting implementations
  • Maintenance burden across multiple files

With Reusable Workflows:

  • Single source of truth for build, test, and coverage operations
  • Consistent Python version testing across all workflows
  • Centralized UV toolchain usage and configuration
  • Simplified maintenance and updates

Consistency Guarantees​

Standardized Operations:

  • All Python builds use identical UV toolchain settings
  • Multi-version testing follows the same comprehensive process
  • Coverage reporting maintains consistent format and upload patterns
  • Test execution uses unified artifact management

Enhanced Maintainability​

Centralized Logic:

  • UV toolchain improvements benefit all workflows automatically
  • Python version updates require changes in single location
  • Bug fixes propagate across entire test system
  • New testing features available to all consuming workflows

Improved Testing​

Component Isolation:

  • Each reusable workflow can be tested independently
  • Clear separation between build, test, and coverage operations
  • Simplified debugging of test failures
  • Consistent artifact organization

Configuration Management​

Parameter Standardization​

All reusable workflows follow consistent parameter naming conventions:

# Standard parameters across Python workflows
inputs:
  python-version:
    description: 'Python version for operations'
    type: string
    default: '3.11'
  
  uv-version:
    description: 'UV version to use'
    type: string
    default: 'latest'
  
  test-type:
    description: 'Type of tests to run'
    type: string
    default: 'unit'

Secret Management​

Inherited Secrets Pattern:

# Consuming workflows pass all secrets to reusable workflows
secrets: inherit

Permission Management​

Standard Permissions:

permissions:
  contents: read        # Repository access
  actions: read        # Artifact access
  checks: write        # Test result reporting

Best Practices​

For Workflow Consumers​

  1. Dependency Order: Ensure proper needs relationships between workflow jobs
  2. Python Version Consistency: Use consistent Python versions across related jobs
  3. Conditional Logic: Use appropriate conditions for optional test operations
  4. Artifact Management: Follow consistent naming for test artifacts
  5. Error Handling: Handle reusable workflow failures appropriately

Performance Optimization​

Matrix Strategies:

# Multi-Python version testing with matrix execution
strategy:
  matrix:
    python-version: ['3.9', '3.10', '3.11', '3.12']
    
uses: ./.github/workflows/rw_uv_run_test_with_multi_py_versions.yaml
with:
  python-versions: ${{ toJson(matrix.python-version) }}

Caching Strategies:

  • UV cache for faster dependency installation
  • Python package cache for faster builds
  • Test artifact caching between workflow runs
  • Coverage report caching for incremental analysis

🔗 Related Documentation: