GitHub Actions Workflow Troubleshooting Guide

GitHub Actions Workflow Troubleshooting Guide

This guide provides comprehensive troubleshooting steps to ensure GitHub Actions workflows run successfully in the MCP Context Provider repository.

🔍 Quick Diagnostic Commands

# Validate all workflows
python scripts/test_workflows.py --report

# Check recent workflow runs
gh run list --limit=10

# View specific workflow run details
gh run view <run-id>

# View failed workflow logs
gh run view <run-id> --log-failed

🛠️ Common Issues and Solutions

1. Permission Errors (403 Forbidden)

Symptoms:

• ⚠️ GitHub release failed with status: 403
• Resource not accessible by integration
• Release creation fails

Root Cause: Missing or insufficient GITHUB_TOKEN permissions in workflow.

Solution: Ensure workflows have proper permissions block:

permissions:
  contents: write    # Required to create releases and upload assets
  actions: read      # Required to read workflow status
  checks: read       # Required to read check results

Applied Fix:

• ✅ Added permissions to .github/workflows/release.yml
• ✅ Added permissions to .github/workflows/ci.yml

2. Missing Files During Build

Symptoms:

• No such file or directory: test_build.py
• Build artifacts not found
• Context files missing

Root Cause: Files excluded by .gitignore or incorrect path references.

Solution:

1. Review .gitignore patterns:

   # Too broad - excludes needed files
   test_*.py
   
   # Better - specific exclusions
   test_server.py
   test_session_init.py
   

2. Verify file paths in workflow:

   ls -la scripts/  # Check if files exist
   git ls-files | grep test  # Check what's tracked
   

Applied Fix:

• ✅ Made .gitignore more specific
• ✅ Added test_build.py to repository

3. Package Naming Issues

Symptoms:

• Package build failed - file not found: mcp-context-provider-1.8.0.dxt
• DXT package created with wrong name

Root Cause: Build script creates package with default name instead of versioned name.

Solution: Update build script to use proper naming:

def move_package_to_root(self, package_file: Path, version: str = None):
    """Move the built package to repository root with proper naming"""
    if version:
        dest_name = f"mcp-context-provider-{version}.dxt"
    else:
        dest_name = "mcp-context-provider.dxt"
    # ... rest of implementation

Applied Fix:

• ✅ Fixed scripts/build_dxt.py package naming
• ✅ Packages now correctly named with version

4. Workflow Not Triggering

Symptoms:

• Push tags but no workflow runs
• Expected workflow doesn't start

Root Cause:

• Incorrect trigger conditions
• Tag naming doesn't match pattern
• Workflow file syntax errors

Solution:

1. Verify trigger patterns:

   on:
     push:
       tags:
         - 'v*'  # Matches v1.8.0, v2.0.0, etc.
   

2. Check tag format:

   git tag v1.8.0        # ✅ Correct
   git tag 1.8.0         # ❌ Won't trigger 'v*' pattern
   

3. Validate workflow syntax:

   python scripts/test_workflows.py
   

5. Environment Variable Issues

Symptoms:

• Context files not loading
• Server configuration errors
• Path-related failures

Root Cause: Missing or incorrect environment variables in workflow.

Solution: Ensure workflows set required environment variables:

env:
  CONTEXT_CONFIG_DIR: contexts
  AUTO_LOAD_CONTEXTS: "true"
  PYTHONPATH: server

🔧 Workflow Validation Framework

Automated Validation

Use the built-in validation script:

# Validate all workflows
python scripts/test_workflows.py --report

# Validate specific workflow
python scripts/test_workflows.py --workflow release.yml

Manual Validation Checklist

1. Permissions Block Present

   • contents: write for releases
   • actions: read for workflow status
   • checks: write for CI results

2. Trigger Configuration

   • Appropriate triggers defined (push, pull_request, etc.)
   • Correct tag patterns for releases
   • Branch filters for CI

3. Job Structure

   • runs-on specified for all jobs
   • Required steps present
   • Action versions up to date

4. Security

   • No hardcoded secrets or tokens
   • Proper use of ${{ secrets.GITHUB_TOKEN }}
   • Environment variables properly configured

5. File Dependencies

   • All referenced files exist in repository
   • Build scripts executable and functional
   • Required dependencies installed

🚀 Best Practices for Reliable Workflows

1. Use Explicit Permissions

Always define minimum required permissions:

permissions:
  contents: write    # Only what you need
  actions: read      # Be specific

2. Version Pin Actions

Use specific action versions for reliability:

- uses: actions/checkout@v4  # ✅ Pinned version
- uses: actions/checkout@main  # ❌ Unstable

3. Add Validation Steps

Include validation in workflows:

- name: Validate workflows
  run: python scripts/test_workflows.py

- name: Validate build process
  run: python scripts/test_build.py

4. Handle Errors Gracefully

Add error handling and cleanup:

- name: Cleanup on failure
  if: failure()
  run: |
    rm -f *.dxt
    rm -rf dxt/

5. Test Locally First

Before pushing tags:

# Test build process
python scripts/build_dxt.py --version 1.8.0

# Validate workflows
python scripts/test_workflows.py --report

# Check workflow syntax
yamllint .github/workflows/

📋 Workflow Health Monitoring

Regular Checks

1. Monthly Workflow Review

   # Check recent workflow success rates
   gh run list --limit=20
   
   # Review failed runs
   gh run list --status=failure --limit=10
   

2. Action Version Updates

   # Check for outdated actions
   python scripts/test_workflows.py --report
   

3. Permission Audits

   # Review workflow permissions
   grep -r "permissions:" .github/workflows/
   

Metrics to Track

• Workflow success rate (target: >95%)
• Build time (target: <5 minutes)
• Time to release (target: <10 minutes)
• Failed workflow recovery time

🆘 Emergency Procedures

Workflow Completely Broken

1. Immediate Actions:

   # Disable automatic workflows
   gh workflow disable <workflow-name>
   
   # Create manual release
   gh release create v1.8.0 --generate-notes package.dxt
   

2. Root Cause Analysis:

   # Check recent changes
   git log --oneline -10 .github/workflows/
   
   # Compare with working version
   git show HEAD~1:.github/workflows/release.yml
   

3. Recovery:

   # Revert to working version
   git checkout HEAD~1 -- .github/workflows/
   
   # Test and commit fix
   python scripts/test_workflows.py --report
   git commit -m "fix: restore working workflow"
   

Release Pipeline Blocked

1. Manual Release Process:

   # Build package locally
   python scripts/build_dxt.py --version 1.8.0
   
   # Create release manually
   gh release create v1.8.0 \\
     --title "Manual Release v1.8.0" \\
     --notes "Emergency manual release" \\
     mcp-context-provider-1.8.0.dxt
   

2. Hotfix Workflow:

   # Create hotfix branch
   git checkout -b hotfix/workflow-fix
   
   # Apply minimal fix
   # Test thoroughly
   # Fast-track review and merge
   

📞 Getting Help

Internal Resources

• Workflow Validation: python scripts/test_workflows.py --report
• Build Testing: python scripts/test_build.py
• Documentation: docs/guides/DEVELOPER_GUIDE.md

External Resources

• GitHub Actions Documentation
• Workflow Syntax Reference
• Troubleshooting Workflows

Emergency Contacts

• Repository Maintainer: Check GitHub repository settings
• CI/CD Issues: Create issue with workflow label
• Security Concerns: Follow security policy guidelines

Summary

This troubleshooting guide covers the most common workflow issues encountered in the MCP Context Provider repository. The implemented solutions include:

• ✅ Permission fixes in workflow files
• ✅ Automated validation with test_workflows.py
• ✅ Build system fixes for proper package naming
• ✅ Comprehensive monitoring and health checks

Regular use of the validation tools and following the best practices outlined here will ensure reliable, successful workflow execution.