feat(workflows): introduce GitHub Actions testing scripts and configu…

.actrc

@@ -0,0 +1,20 @@
+# Act configuration for flutter_policy_engine
+# This file is auto-generated by test_github_actions.sh
+
+# Use medium-sized image for better compatibility
+-P ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Environment variables
+--env-file .env
+
+# Secrets (you can create a .secrets file for local testing)
+--secret-file .secrets
+
+# Bind mounts for better performance
+--bind
+
+# Reuse containers when possible
+--reuse
+
+# Show timestamps
+--verbose

.github/workflows/check-commits.yml

@@ -3,6 +3,9 @@ name: 🛡️ Validate Commit Messages
 on:
   push:
   pull_request:
+    branches-ignore:
+      - main
+      - develop
 
 jobs:
   check-commits:

.github/workflows/develop-branch-pipeline.yml

@@ -0,0 +1,67 @@
+name: 🚀 Main Branch Pipeline
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+jobs:
+  # Step 1: Validate commit messages
+  check-commits:
+    name: Validate Commit Messages
+    runs-on: ubuntu-latest
+    outputs:
+      commits-validated: ${{ steps.validate-commits.outputs.result }}
+    steps:
+      - name: ⬇️ Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: ⬢ Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install Commitlint
+        run: |
+          npm install --save-dev @commitlint/{config-conventional,cli}
+
+      - name: 🔍 Validate commit messages (entire branch)
+        id: validate-commits
+        run: |
+          npx commitlint --from=$(git rev-list --max-parents=0 HEAD) --to=HEAD --verbose
+          echo "result=success" >> $GITHUB_OUTPUT
+
+  # Step 2: Run Flutter tests
+  test:
+    name: Flutter Tests & Coverage
+    runs-on: ubuntu-latest
+    needs: check-commits
+    if: needs.check-commits.outputs.commits-validated == 'success'
+    outputs:
+      tests-passed: ${{ steps.run-tests.outputs.result }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.29.3"
+          architecture: "x64"
+
+      - name: Install dependencies
+        run: flutter pub get
+
+      - name: Verify formatting
+        run: dart format --set-exit-if-changed .
+
+      - name: Analyze project source
+        run: flutter analyze
+
+      - name: Run tests with coverage
+        id: run-tests
+        run: |
+          flutter test --coverage
+          echo "result=success" >> $GITHUB_OUTPUT

.github/workflows/main-branch-pipeline.yml

@@ -1,9 +1,6 @@
 name: 🚀 Main Branch Pipeline
 
 on:
-  push:
-    branches:
-      - main
   pull_request:
     branches:
       - main
@@ -89,28 +86,3 @@ jobs:
         run: |
           flutter test --coverage
           echo "result=success" >> $GITHUB_OUTPUT
-
-  # Step 4: Release
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    needs: test
-    if: needs.test.outputs.tests-passed == 'success'
-    steps:
-      - name: ⬇️ Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: ⬢ Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: 📦 Install dependencies
-        run: npm ci
-
-      - name: 🚀 Run semantic-release
-        env:
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
-        run: npx semantic-release

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: 🚀 Release Pipeline
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-push:
+    name: Release Push
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: ⬢ Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🚀 Run semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: npx semantic-release

README.md

@@ -165,6 +165,34 @@ genhtml coverage/lcov.info -o coverage/html
 open coverage/html/index.html
 ```
 
+### GitHub Actions Testing
+
+Test GitHub Actions workflows locally before pushing to GitHub:
+
+```bash
+# Install dependencies (first time only)
+./scripts/install_dependencies.sh
+
+# Test a specific workflow
+./scripts/test_github_actions.sh -w .github/workflows/check-commits.yml --dry-run
+
+# List available workflows
+./scripts/test_github_actions.sh --list-workflows
+
+# Test with verbose output
+./scripts/test_github_actions.sh -w .github/workflows/main-branch-pipeline.yml -v
+```
+
+**Features:**
+
+- 🐳 Docker-based local testing with `act`
+- 🔍 Workflow validation and syntax checking
+- 🧪 Dry-run mode for safe testing
+- 📋 Comprehensive workflow coverage
+- 🛠️ Automatic dependency management
+
+For detailed usage, see [GitHub Actions Testing Guide](scripts/README.md).
+
 ### Example App
 
 Explore the interactive example app:

scripts/CHANGELOG.md

@@ -0,0 +1,114 @@
+# GitHub Actions Testing Scripts Changelog
+
+## [1.0.0] - 2025-07-24
+
+### Added
+
+- **GitHub Actions Testing Script** (`test_github_actions.sh`)
+
+  - Comprehensive script to test GitHub Actions workflows locally using `act` and Docker
+  - Support for all project workflows: main-branch-pipeline, develop-branch-pipeline, check-commits, and release
+  - Dry-run mode for safe testing without execution
+  - Verbose output for debugging
+  - Automatic workflow validation and syntax checking
+  - Smart defaults based on workflow type
+  - Colored output with timestamps
+  - Automatic cleanup of Docker containers
+
+- **Dependency Installation Script** (`install_dependencies.sh`)
+
+  - Cross-platform installation of `act` CLI tool
+  - Docker installation and setup guidance
+  - Python dependencies management (PyYAML for YAML validation)
+  - Automatic environment file setup (.env and .secrets)
+  - Installation verification and health checks
+  - Support for macOS, Linux, and Windows
+
+- **Configuration Files**
+
+  - `.actrc` - Optimized act configuration for the project
+  - `env.example` - Template for environment variables
+  - `secrets.example` - Template for secrets configuration
+  - Comprehensive documentation in `README.md`
+
+- **Documentation**
+  - Detailed usage guide with examples
+  - Troubleshooting section
+  - Integration examples for CI/CD pipelines
+  - Pre-commit hook examples
+  - Cross-platform installation instructions
+
+### Features
+
+- **Workflow Testing**: Test any GitHub Actions workflow locally before pushing
+- **Event Simulation**: Simulate push, pull_request, and other GitHub events
+- **Branch Support**: Test workflows with different branch scenarios
+- **Validation**: YAML syntax validation and workflow correctness checking
+- **Performance**: Optimized Docker image usage and container reuse
+- **Safety**: Dry-run mode prevents accidental execution
+- **Debugging**: Verbose mode for detailed troubleshooting
+
+### Supported Workflows
+
+1. **Main Branch Pipeline** - Validates PRs to main branch
+2. **Develop Branch Pipeline** - Validates PRs to develop branch
+3. **Check Commits** - Validates commit messages on all branches
+4. **Release Pipeline** - Tests semantic-release automation
+
+### Prerequisites
+
+- Docker (running)
+- Git repository
+- act CLI (auto-installed by script)
+- Python 3 (optional, for enhanced YAML validation)
+
+### Quick Start
+
+```bash
+# Install dependencies
+./scripts/install_dependencies.sh
+
+# Test a workflow
+./scripts/test_github_actions.sh -w .github/workflows/check-commits.yml --dry-run
+
+# List available workflows
+./scripts/test_github_actions.sh --list-workflows
+```
+
+### Breaking Changes
+
+None - This is a new feature addition.
+
+### Deprecations
+
+None.
+
+### Removed
+
+None.
+
+### Fixed
+
+None.
+
+### Security
+
+- Secure handling of secrets through `.secrets` file
+- Automatic cleanup of Docker containers
+- Validation of workflow files before execution
+- Safe defaults for environment variables
+
+### Performance
+
+- Optimized Docker image selection (`catthehacker/ubuntu:act-latest`)
+- Container reuse for faster subsequent runs
+- Bind mounts for better performance
+- Efficient workflow parsing and validation
+
+### Documentation
+
+- Comprehensive README with examples
+- Inline help for all scripts
+- Troubleshooting guide
+- Integration examples
+- Cross-platform installation instructions