Workflow Trigger with Caching

🚀 Workflow Trigger Action

A robust and intelligent GitHub Action for triggering workflows with advanced caching mechanisms, fallback strategies, and retry logic.

🌟 Key Features

🧠 Smart Caching: Combines file-based and ETag-based caching for optimal performance
🔄 Automatic Fallbacks: Works even during API outages through local workflow detection
⚡ Retry Mechanism: Exponential backoff for rate-limiting and temporary failures
🎯 Flexible Filtering: Precise workflow selection via name prefix matching
📊 Detailed Outputs: Comprehensive information about triggered workflows
🛡️ Production-Ready: Robust error handling for enterprise environments

🎯 Core Capabilities

Intelligent Workflow Management

Automatic Discovery: Finds workflows via GitHub API or local files
Prefix Filtering: Triggers only workflows matching specific name patterns
Batch Processing: Efficient handling of multiple workflows

Performance Optimization

Multi-Level Caching:
- File cache (30min default)
- ETag-based validation
- Automatic cache invalidation
Rate Limit Management: Smart handling of API limits
Optimized Sequencing: Efficient workflow trigger patterns

Enterprise Features

Graceful Degradation: Continues working during API issues
Comprehensive Logging: Detailed status information
Monitoring Integration: Outputs for external monitoring systems

🚀 Quick Start

Basic Usage

name: Deploy Staging
on: [push]

jobs:
  trigger-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trigger Docker Stage Workflows
        uses: sushidev-team/workflow-trigger-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          workflow_prefix: 'docker-stage'

Advanced Configuration

- name: Trigger Production Deployment
  id: deploy
  uses: sushidev-team/workflow-trigger-action@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    target_repo: 'company/production-repo'
    workflow_prefix: 'deploy-prod'
    ref: ${{ github.ref_name }}
    cache_max_age: '3600'
    workflow_inputs: |
      {
        "version": "${{ github.sha }}",
        "environment": "production",
        "triggered_by": "${{ github.actor }}",
        "deployment_type": "automated"
      }

- name: Report Results
  run: |
    echo "✅ Triggered ${{ steps.deploy.outputs.triggered_workflows }} workflows"
    echo "📋 Workflow IDs: ${{ steps.deploy.outputs.workflow_ids }}"

📋 Inputs & Outputs

Inputs

Parameter	Description	Required	Default	Example
`github_token`	GitHub token for API access	✅	-	`${{ secrets.GITHUB_TOKEN }}`
`target_repo`	Target repository (owner/repo format)	❌	`${{ github.repository }}`	`company/backend-services`
`workflow_prefix`	Workflow name prefix for filtering	❌	`docker-stage`	`deploy-`, `build-prod`
`ref`	Git reference to trigger workflows on	❌	`master`	`main`, `develop`, `v1.2.3`
`cache_max_age`	Cache validity in seconds	❌	`1800`	`3600` (1h), `7200` (2h)
`workflow_inputs`	JSON inputs for triggered workflows	❌	`{}`	See examples below

Outputs

Output	Description	Type	Example
`triggered_workflows`	Number of workflows triggered	Number	`3`
`workflow_ids`	Comma-separated list of triggered workflow IDs	String	`12345,67890,11111`

🔧 Usage Examples

Cross-Repository Triggering

name: Multi-Repo Deployment

jobs:
  deploy-microservices:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [user-service, payment-service, notification-service]
    steps:
      - name: Deploy ${{ matrix.service }}
        uses: sushidev-team/workflow-trigger-action@v1
        with:
          github_token: ${{ secrets.DEPLOY_TOKEN }}
          target_repo: company/${{ matrix.service }}
          workflow_prefix: 'deploy-production'
          workflow_inputs: |
            {
              "version": "${{ github.sha }}",
              "service_name": "${{ matrix.service }}",
              "environment": "production"
            }

Conditional Triggering

- name: Trigger Workflows Based on Changes
  uses: sushidev-team/workflow-trigger-action@v1
  if: contains(github.event.head_commit.message, '[deploy]')
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    workflow_prefix: ${{ github.event.head_commit.message contains '[prod]' && 'deploy-prod' || 'deploy-stage' }}
    workflow_inputs: |
      {
        "commit_message": "${{ github.event.head_commit.message }}",
        "author": "${{ github.event.head_commit.author.name }}"
      }

Multiple Workflow Types

jobs:
  trigger-pipeline:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        stage: 
          - { prefix: 'build-', environment: 'build' }
          - { prefix: 'test-', environment: 'testing' }
          - { prefix: 'deploy-stage-', environment: 'staging' }
          - { prefix: 'deploy-prod-', environment: 'production' }
    steps:
      - name: Trigger ${{ matrix.stage.environment }} workflows
        uses: sushidev-team/workflow-trigger-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          workflow_prefix: ${{ matrix.stage.prefix }}
          workflow_inputs: |
            {
              "stage": "${{ matrix.stage.environment }}",
              "version": "${{ github.sha }}"
            }

Custom Workflow Inputs

- name: Trigger with Dynamic Inputs
  uses: sushidev-team/workflow-trigger-action@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    workflow_prefix: 'custom-deploy'
    workflow_inputs: |
      {
        "version": "${{ github.sha }}",
        "environment": "${{ github.ref_name == 'main' && 'production' || 'staging' }}",
        "feature_flags": {
          "new_ui": true,
          "beta_features": ${{ github.ref_name == 'develop' }}
        },
        "deployment_config": {
          "replicas": ${{ github.ref_name == 'main' && 5 || 2 }},
          "resources": {
            "cpu": "500m",
            "memory": "1Gi"
          }
        }
      }

🗂️ Caching System

The action implements a sophisticated two-tier caching system:

File-Based Caching

Stores workflow data locally for configurable duration
Default: 30 minutes (cache_max_age: 1800)
Survives across job runs within the same workflow

ETag-Based Caching

Uses GitHub API ETags to avoid unnecessary requests
Automatically validates cache freshness
Reduces API rate limit consumption

Cache Behavior

Request Flow:
1. Check file cache age → Use if fresh
2. Check ETag cache → Send conditional request
3. API responds:
   - 304 Not Modified → Use cached data
   - 200 OK → Update cache with new data
   - 403/429/5xx → Fall back to local workflows

🛡️ Error Handling

Retry Logic

Exponential Backoff: 10s, 20s, 30s delays for rate limits
Rate Limit Handling: Automatic retry with increasing delays
Network Failures: Up to 3 retry attempts per workflow

Fallback Mechanisms

API Failures: Automatically switches to local workflow detection
Permission Issues: Graceful degradation with informative logging
Missing Workflows: Continues execution without failing the job

Error Scenarios

# The action handles these gracefully:
- GitHub API rate limits (403/429)
- Network timeouts
- Invalid repository access
- Missing workflow files
- Malformed workflow inputs

📚 Best Practices

Security

# Use dedicated tokens for cross-repo access
- name: Deploy to Production
  uses: sushidev-team/workflow-trigger-action@v1
  with:
    github_token: ${{ secrets.DEPLOY_PAT }}  # Personal Access Token
    target_repo: 'company/production-repo'

Performance

# Optimize caching for frequent workflows
- uses: sushidev-team/workflow-trigger-action@v1
  with:
    cache_max_age: '7200'  # 2 hours for stable workflows
    workflow_prefix: 'deploy-prod'

Monitoring

# Track deployment metrics
- name: Monitor Deployments
  if: always()
  run: |
    echo "::notice::Triggered ${{ steps.deploy.outputs.triggered_workflows }} workflows"
    echo "deployment_count=${{ steps.deploy.outputs.triggered_workflows }}" >> $GITHUB_ENV

🔧 Troubleshooting

Common Issues

Issue: No workflows found with prefix

# Check if workflows exist
curl -H "Authorization: token $TOKEN" \
  https://api.github.com/repos/owner/repo/actions/workflows

# Verify workflow names in .github/workflows/
ls -la .github/workflows/

Issue: Permission denied (403)

# Ensure token has sufficient permissions
permissions:
  actions: write
  contents: read

Issue: Rate limit exceeded

# Increase cache duration and add delays
- uses: sushidev-team/workflow-trigger-action@v1
  with:
    cache_max_age: '3600'  # 1 hour cache

Debug Mode

# Enable verbose logging
- uses: sushidev-team/workflow-trigger-action@v1
  env:
    ACTIONS_STEP_DEBUG: true

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/sushidev-team/workflow-trigger-action.git
cd workflow-trigger-action

# Test locally
act -j test

# Run tests
npm test

Reporting Issues

Use the issue tracker
Include workflow logs and error messages
Specify your GitHub Actions runner environment

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Credits

Created and maintained by Sushi Dev GmbH.

Contributors

Add your name here by contributing!

📊 Changelog

[v1.0.0] - 2025-01-XX

Initial release
Smart caching implementation
Fallback mechanism for API failures
Retry logic with exponential backoff
Comprehensive error handling

Star ⭐ this repository if you find it useful!