feat: add automated Portainer stack management workflow

[nsheaps]

Summary

This PR introduces an automated GitHub Actions workflow for managing Portainer stacks, enabling automatic redeployment of stacks when configuration files change.

What's Changed

🚀 New Features

• Automated Stack Detection: Automatically detects docker-compose.yaml files in the hosts/ directory
• Smart Redeployment: Uses Portainer's StackGitRedeploy API endpoint to trigger redeployment for existing stacks
• Webhook Integration: Optional webhook notifications when stacks are updated
• Scheduled Monitoring: Runs automatically every 30 minutes to catch any missed changes

📁 Files Added

• .github/workflows/manage-portainer-stacks.yml: Main GitHub Actions workflow
• .github/PORTAINER_SETUP.md: Comprehensive setup documentation

Technical Details

Workflow Triggers

• Push Events: Triggers on pushes to main branch affecting stack files
• Manual Dispatch: Can be run manually via GitHub Actions UI
• Scheduled: Runs every 30 minutes for continuous monitoring

Stack Detection Logic

• Scans hosts/ directory for docker-compose.yaml files
• Uses parent directory name as stack name (e.g., hosts/heapsnas/nextcloud/docker-compose.yaml → nextcloud)
• Processes up to 10 stack files per run

API Integration

• Uses Portainer's StackGitRedeploy endpoint (PUT /api/stacks/{id}/git/redeploy)
• Automatically detects existing stacks vs new stacks
• Supports environment variables and custom repository references

Setup Requirements

Required GitHub Repository Secrets

• PORTAINER_URL: Your Portainer instance URL
• PORTAINER_API_TOKEN: Portainer API token with stack management permissions

Optional Secrets

• STACK_WEBHOOK_URL: URL for receiving webhook notifications

Security Considerations

• API tokens require Stack read/write and Endpoint read/write permissions
• Consider using restricted tokens for production environments
• Token rotation recommended

Testing Plan

• Configure required secrets in GitHub repository
• Test manual workflow execution
• Verify stack detection works correctly
• Test webhook notifications (if enabled)
• Validate error handling for failed API calls

Breaking Changes

None - this is a non-breaking addition that complements existing stack management workflows.

Future Enhancements

• Stack creation functionality (currently only handles redeployment)
• Enhanced error handling and retry mechanisms
• Support for multiple Portainer endpoints
• Slack/Teams notifications for stack deployment status
• Cost optimization for API calls and workflow runs

🤖 Generated with Claude Code