From 5f08238698260fb179307efdf0ba8062f4f7b0e0 Mon Sep 17 00:00:00 2001 From: Harmanpreet Kaur Date: Tue, 9 Dec 2025 21:58:33 +0530 Subject: [PATCH 1/5] feat: update GitHub Actions workflows with path-based triggers and comprehensive documentation --- .github/workflows/codeql.yml | 14 + .github/workflows/deploy.yml | 22 ++ .github/workflows/docker-build-and-push.yml | 10 + .github/workflows/pylint.yml | 14 +- .github/workflows/test.yml | 19 +- docs/GitHubActionsWorkflows.md | 325 ++++++++++++++++++++ 6 files changed, 402 insertions(+), 2 deletions(-) create mode 100644 docs/GitHubActionsWorkflows.md diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 14ce486fd..75ba65b4f 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -14,8 +14,22 @@ name: "CodeQL Advanced" on: push: branches: [ "main", "dev", "demo" ] + paths: + - 'src/**/*.py' + - 'src/**/*.js' + - 'src/**/*.ts' + - 'src/**/*.tsx' + - 'tests/**/*.py' + - '.github/workflows/codeql.yml' pull_request: branches: [ "main", "dev", "demo" ] + paths: + - 'src/**/*.py' + - 'src/**/*.js' + - 'src/**/*.ts' + - 'src/**/*.tsx' + - 'tests/**/*.py' + - '.github/workflows/codeql.yml' schedule: - cron: '44 20 * * 2' diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index c2036be6e..06c90fe60 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,6 +1,28 @@ name: Validate Deployment v3 on: + push: + branches: + - main + - dev-v3 + - hotfix + paths: + - 'infra/main.bicep' + - 'infra/modules/**/*.bicep' + - 'infra/*.parameters.json' + - 'infra/scripts/**' + - '.github/workflows/deploy.yml' + pull_request: + branches: + - main + - dev-v3 + - hotfix + paths: + - 'infra/main.bicep' + - 'infra/modules/**/*.bicep' + - 'infra/*.parameters.json' + - 'infra/scripts/**' + - '.github/workflows/deploy.yml' workflow_run: workflows: ["Build Docker and Optional Push v3"] types: diff --git a/.github/workflows/docker-build-and-push.yml b/.github/workflows/docker-build-and-push.yml index eb46863e5..7ecd9ffb0 100644 --- a/.github/workflows/docker-build-and-push.yml +++ b/.github/workflows/docker-build-and-push.yml @@ -7,6 +7,11 @@ on: - dev-v3 - demo-v3 - hotfix + paths: + - 'src/frontend/**' + - 'src/backend/**' + - 'src/mcp_server/**' + - '.github/workflows/docker-build-and-push.yml' pull_request: types: - opened @@ -18,6 +23,11 @@ on: - dev-v3 - demo-v3 - hotfix + paths: + - 'src/frontend/**' + - 'src/backend/**' + - 'src/mcp_server/**' + - '.github/workflows/docker-build-and-push.yml' workflow_dispatch: jobs: diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml index bc2851159..b141bbc71 100644 --- a/.github/workflows/pylint.yml +++ b/.github/workflows/pylint.yml @@ -1,6 +1,18 @@ name: PyLint -on: [push] +on: + push: + paths: + - 'src/backend/**/*.py' + - 'src/backend/requirements.txt' + - '.flake8' + - '.github/workflows/pylint.yml' + pull_request: + paths: + - 'src/backend/**/*.py' + - 'src/backend/requirements.txt' + - '.flake8' + - '.github/workflows/pylint.yml' jobs: build: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7d8ca7c0b..48c9b85e9 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -7,6 +7,15 @@ on: - dev - demo - hotfix + paths: + - 'src/backend/**/*.py' + - 'src/tests/**/*.py' + - 'src/mcp_server/**/*.py' + - 'pytest.ini' + - 'conftest.py' + - 'src/backend/requirements.txt' + - 'pyproject.toml' + - '.github/workflows/test.yml' pull_request: types: - opened @@ -14,11 +23,19 @@ on: - reopened - synchronize branches: - - main - main - dev - demo - hotfix + paths: + - 'src/backend/**/*.py' + - 'src/tests/**/*.py' + - 'src/mcp_server/**/*.py' + - 'pytest.ini' + - 'conftest.py' + - 'src/backend/requirements.txt' + - 'pyproject.toml' + - '.github/workflows/test.yml' jobs: test: diff --git a/docs/GitHubActionsWorkflows.md b/docs/GitHubActionsWorkflows.md new file mode 100644 index 000000000..176bb6d6d --- /dev/null +++ b/docs/GitHubActionsWorkflows.md @@ -0,0 +1,325 @@ +# GitHub Actions Workflows Documentation + +This document provides a comprehensive guide to all GitHub Actions workflows in this repository, including when they run, what triggers them, and their specific purposes. + +## Overview + +The repository uses path-based triggers to ensure workflows only run when relevant files are modified, optimizing CI/CD performance and providing clearer PR feedback. + +## Workflow Summary Table + +| Workflow | Triggers | Purpose | Files Monitored | +|----------|----------|---------|-----------------| +| **Docker Build & Push** | Push/PR + Paths | Build and push Docker images for frontend, backend, and MCP server | `src/frontend/`, `src/backend/`, `src/mcp_server/` only | +| **PyLint** | Push/PR + Paths | Python code linting and quality checks (backend only) | `src/backend/` Python files, requirements.txt, .flake8 config | +| **CodeQL** | Push/PR + Paths + Schedule | Security and code quality analysis | Source code files only (Python, JS, TS, TSX), test Python files | +| **Test Workflow with Coverage** | Push/PR + Paths | Python unit tests with coverage reporting (backend-focused) | Backend, MCP, tests Python files, backend requirements | +| **Test Automation** | Push/PR + Paths + Manual | Run automated tests | Python files, test files, requirements | +| **Validate Deployment** | Push/PR + Paths + Schedule + Manual | Infrastructure validation and deployment | Main Bicep template, modules, parameters, infra scripts only | +| **Broken Link Checker** | PR + Paths + Manual | Check documentation links | Markdown files | + +--- + +## Detailed Workflow Documentation + +### 1. Docker Build and Push (`docker-build-and-push.yml`) + +**Purpose**: Builds and optionally pushes Docker images for the three main components of the application. + +**When it runs**: +- **Push** to branches: `main`, `dev-v3`, `demo-v3`, `hotfix` +- **Pull Requests** targeting these branches +- **Manual trigger** (`workflow_dispatch`) + +**Path Filters** - Only runs when these files change: +```yaml +- 'src/frontend/**' # Frontend React application +- 'src/backend/**' # Python backend API +- 'src/mcp_server/**' # MCP (Model Context Protocol) server +- '.github/workflows/docker-build-and-push.yml' # This workflow file +``` + +**What it does**: +1. Builds three Docker images: `macaebackend`, `macaefrontend`, `macaemcp` +2. Pushes images to Azure Container Registry (ACR) when on protected branches +3. Tags images with branch-specific tags and historical tags +4. Skips push for pull requests (build-only validation) + +### 2. Python Linting (`pylint.yml`) + +**Purpose**: Ensures Python code quality and adherence to coding standards using Flake8. + +**When it runs**: +- **Push** to any branch +- **Pull Requests** to any branch + +**Path Filters** - Only runs when these files change: +```yaml +- 'src/backend/**/*.py' # Backend Python files (only files actually linted) +- 'src/backend/requirements.txt' # Backend dependencies (only file actually installed) +- '.flake8' # Flake8 configuration (only config file actually used) +- '.github/workflows/pylint.yml' # This workflow file +``` + +**What it does**: +1. Sets up Python 3.11 environment +2. Installs dependencies from backend requirements +3. Runs Flake8 linting on the backend code + +### 3. CodeQL Code Scanning (`codeql.yml`) + +**Purpose**: Performs security and code quality analysis using GitHub's CodeQL engine. + +**When it runs**: +- **Push** to branches: `main`, `dev`, `demo` +- **Pull Requests** targeting these branches +- **Scheduled** runs: Every Tuesday at 8:44 PM UTC + +**Path Filters** - Only runs when these files change: +```yaml +- 'src/**/*.py' # All Python source code files +- 'src/**/*.js' # All JavaScript source code files +- 'src/**/*.ts' # All TypeScript source code files +- 'src/**/*.tsx' # All TypeScript JSX source code files +- 'tests/**/*.py' # Python test files only (no .jsx files exist) +- '.github/workflows/codeql.yml' # This workflow file +``` + +**What it does**: +1. Analyzes JavaScript/TypeScript and Python code +2. Identifies security vulnerabilities and code quality issues +3. Creates alerts for any findings +4. Runs automatically on schedule for continuous monitoring + +### 4. Test Workflow with Coverage (`test.yml`) + +**Purpose**: Runs Python unit tests with coverage reporting for code quality assurance (backend-focused). + +**When it runs**: +- **Push** to branches: `main`, `dev`, `demo`, `hotfix` +- **Pull Requests** targeting these branches + +**Path Filters** - Only runs when these files change: +```yaml +- 'src/backend/**/*.py' # Backend Python files (actually tested) +- 'src/tests/**/*.py' # Source test files (actually tested) +- 'src/mcp_server/**/*.py' # MCP server Python files (actually tested) +- 'pytest.ini' # Pytest configuration +- 'conftest.py' # Pytest configuration +- 'src/backend/requirements.txt' # Backend requirements (actually installed) +- 'pyproject.toml' # Python project configuration +- '.github/workflows/test.yml' # This workflow file +``` + +**What it does**: +1. Sets up Python environment +2. Installs dependencies from requirements files +3. Runs unit tests with pytest +4. Generates code coverage reports +5. Validates code quality metrics + +### 5. Test Automation (`test-automation.yml`) + +**Purpose**: Runs automated end-to-end tests against deployed instances. + +**When it runs**: +- **Push** to any branch +- **Pull Requests** to any branch +- **Manual trigger** (`workflow_dispatch`) +- **Called by other workflows** (`workflow_call`) + +**Path Filters** - Only runs when these files change: +```yaml +- 'src/**/*.py' # All Python source files +- 'tests/**' # All test files +- 'src/tests/**' # Source test files +- 'pytest.ini' # Pytest configuration +- 'conftest.py' # Pytest configuration +- 'requirements*.txt' # Any requirements files +- 'src/backend/requirements*.txt' # Backend requirements +- 'src/mcp_server/requirements*.txt' # MCP server requirements +- '.github/workflows/test-automation.yml' # This workflow file +``` + +**What it does**: +1. Sets up Python 3.13 environment +2. Authenticates with Azure +3. Runs automated tests against deployed MACAE instances +4. Can be configured with various test parameters + +### 6. Validate Deployment (`deploy.yml`) + +**Purpose**: Validates Azure infrastructure and performs deployments. + +**When it runs**: +- **Push** to branches: `main`, `dev-v3`, `hotfix` +- **Pull Requests** targeting these branches +- **After successful Docker builds** (`workflow_run`) +- **Scheduled** runs: Daily at 11:00 AM and 11:00 PM GMT +- **Manual trigger** (`workflow_dispatch`) + +**Path Filters** - Only runs when these files change: +```yaml +- 'infra/main.bicep' # Main Bicep template (actually used) +- 'infra/modules/**/*.bicep' # Bicep module files (actually used) +- 'infra/*.parameters.json' # Parameter files (actually used) +- 'infra/scripts/**' # Infrastructure scripts (actually used) +- '.github/workflows/deploy.yml' # This workflow file +``` + +**What it does**: +1. Checks Azure quota requirements +2. Creates or validates resource groups +3. Deploys Bicep templates to Azure +4. Configures deployed resources +5. Runs end-to-end tests +6. Cleans up resources if configured + +### 7. Broken Link Checker (`broken-links-checker.yml`) + +**Purpose**: Validates links in documentation files. + +**When it runs**: +- **Pull Requests** (any branch) +- **Manual trigger** (`workflow_dispatch`) + +**Path Filters** - Only runs when these files change: +```yaml +- '**/*.md' # All Markdown files +``` + +**What it does**: +1. Scans all Markdown files for links +2. Validates that links are accessible +3. Reports any broken links found + +--- + +## Workflow Dependencies + +```mermaid +graph TD + A[Docker Build & Push] --> B[Validate Deployment] + B --> C[Test Automation] + D[PyLint] --> E[Code Quality Gate] + F[CodeQL] --> E + E --> G[Deployment Approval] +``` + +### Dependency Chain: +1. **Code Quality Checks** (PyLint, CodeQL) run independently +2. **Docker Build & Push** must complete successfully +3. **Validate Deployment** triggers after successful Docker builds +4. **Test Automation** runs as part of deployment validation + +--- + +## Branch-Specific Behavior + +### Protected Branches (`main`, `dev-v3`, `demo-v3`, `hotfix`) +- Docker images are **pushed** to ACR +- Full deployment validation occurs +- Scheduled workflows run +- All quality gates must pass + +### Feature Branches +- Docker images are **built only** (not pushed) +- Deployment validation skipped +- Code quality checks still run +- Faster feedback loop for development + +### Pull Requests +- All path-filtered workflows run for validation +- No deployment or image pushing occurs +- Provides comprehensive validation before merge + +--- + +## Path Filter Benefits + +### Performance Optimization +- **Reduced CI/CD time**: Only relevant workflows run +- **Lower resource usage**: No unnecessary job executions +- **Faster feedback**: Developers get quicker PR status updates +- **Optimized triggers**: Paths are precisely matched to what each workflow actually uses + +### Clearer PR Status +- PR checks only show relevant pipeline results +- Easier to identify which changes need attention +- Reduced noise from unrelated workflow failures + +### Recent Optimizations (December 2025) +All workflow path filters have been optimized to only include files that are actually used by each workflow: + +- **Docker Build & Push**: Removed unused Dockerfile patterns, requirements files, and lock files not in source directories +- **PyLint**: Streamlined to only backend Python files, specific requirements.txt, and .flake8 config (workflow only lints backend) +- **CodeQL**: Removed non-existent .jsx files, focused on actual source code files +- **Test Workflow**: Aligned with backend-focused testing approach, removed unused requirements patterns +- **Validate Deployment**: Removed unused custom templates and Azure config files not referenced by workflow + +**Result**: Significantly reduced false triggers from files like `.env.sample`, documentation changes, or configuration files that don't affect specific workflows. + +### Examples of Path-Based Triggering + +| Change Type | Workflows That Run | +|-------------|-------------------| +| Update React component in `src/frontend/` | Docker Build & Push, CodeQL | +| Modify Python API in `src/backend/` | Docker Build & Push, PyLint, CodeQL, Test with Coverage | +| Update MCP server in `src/mcp_server/` | Docker Build & Push, CodeQL, Test with Coverage | +| Update main Bicep template in `infra/main.bicep` | Validate Deployment | +| Update `.flake8` configuration | PyLint | +| Edit `.env.sample` files | **No workflows run** (optimized out) | +| Update documentation in `docs/` | Broken Link Checker (if .md files) | +| Update GitHub workflow file | The specific workflow + any dependent workflows | + +--- + +## Manual Workflow Triggers + +All workflows support manual triggering through the GitHub Actions UI: + +1. Go to **Actions** tab in GitHub +2. Select the desired workflow +3. Click **Run workflow** +4. Choose branch and provide any required inputs + +### Workflows with Additional Inputs +- **Validate Deployment**: Various Azure configuration options +- **Test Automation**: Test parameters and environment settings + +--- + +## Troubleshooting + +### Workflow Not Running When Expected +1. **Check path filters**: Ensure your changes match the path patterns +2. **Verify branch targeting**: Some workflows only run on specific branches +3. **Review workflow file**: Check for syntax errors in YAML + +### All Workflows Running Despite Path Filters +- Workflows always run when their own file (`.yml`) is modified +- Changes to root-level configuration files may trigger multiple workflows +- Manual triggers bypass path filtering + +### Performance Issues +- Path filters are working correctly if you see fewer workflow runs +- Check workflow run history to verify optimal triggering +- Contact maintainers if you notice performance degradation + +--- + +## Maintenance + +### Adding New Path Filters +1. Identify which files should trigger the workflow +2. Update the `paths:` section in the workflow YAML +3. Test with a sample PR to verify correct behavior +4. Update this documentation + +### Modifying Existing Filters +1. Consider impact on existing development workflows +2. Test changes in a feature branch first +3. Update documentation to reflect changes +4. Communicate changes to the development team + +For questions or issues with GitHub Actions workflows, please refer to the [troubleshooting guide](TroubleShootingSteps.md) or create an issue in this repository. \ No newline at end of file From c5b811b7500cdc299b3047307e0ddf1c8dfad0f3 Mon Sep 17 00:00:00 2001 From: Harmanpreet-Microsoft Date: Tue, 9 Dec 2025 22:32:16 +0530 Subject: [PATCH 2/5] Add new file jnfhe with initial content --- jnfhe | 1 + 1 file changed, 1 insertion(+) create mode 100644 jnfhe diff --git a/jnfhe b/jnfhe new file mode 100644 index 000000000..82f4bbfc5 --- /dev/null +++ b/jnfhe @@ -0,0 +1 @@ +hadhhddf From 5d96874343bb40457876c0dd9b37079500dbb5ac Mon Sep 17 00:00:00 2001 From: Harmanpreet-Microsoft Date: Tue, 9 Dec 2025 22:33:30 +0530 Subject: [PATCH 3/5] Delete jnfhe --- jnfhe | 1 - 1 file changed, 1 deletion(-) delete mode 100644 jnfhe diff --git a/jnfhe b/jnfhe deleted file mode 100644 index 82f4bbfc5..000000000 --- a/jnfhe +++ /dev/null @@ -1 +0,0 @@ -hadhhddf From e9bd9f774264b14d5348c6a9366136ca2724f044 Mon Sep 17 00:00:00 2001 From: Harmanpreet-Microsoft Date: Tue, 16 Dec 2025 16:00:06 +0530 Subject: [PATCH 4/5] Update deploy.yml --- .github/workflows/deploy.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 06c90fe60..bba1f34ae 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -13,6 +13,11 @@ on: - 'infra/scripts/**' - '.github/workflows/deploy.yml' pull_request: + types: + - opened + - ready_for_review + - reopened + - synchronize branches: - main - dev-v3 From 1ebfd694d93794b6df872f67e12c979c8beecdaf Mon Sep 17 00:00:00 2001 From: Harmanpreet Kaur Date: Tue, 16 Dec 2025 16:42:48 +0530 Subject: [PATCH 5/5] chore:GitHub Actions workflows --- docs/GitHubActionsWorkflows.md | 325 --------------------------------- 1 file changed, 325 deletions(-) delete mode 100644 docs/GitHubActionsWorkflows.md diff --git a/docs/GitHubActionsWorkflows.md b/docs/GitHubActionsWorkflows.md deleted file mode 100644 index 176bb6d6d..000000000 --- a/docs/GitHubActionsWorkflows.md +++ /dev/null @@ -1,325 +0,0 @@ -# GitHub Actions Workflows Documentation - -This document provides a comprehensive guide to all GitHub Actions workflows in this repository, including when they run, what triggers them, and their specific purposes. - -## Overview - -The repository uses path-based triggers to ensure workflows only run when relevant files are modified, optimizing CI/CD performance and providing clearer PR feedback. - -## Workflow Summary Table - -| Workflow | Triggers | Purpose | Files Monitored | -|----------|----------|---------|-----------------| -| **Docker Build & Push** | Push/PR + Paths | Build and push Docker images for frontend, backend, and MCP server | `src/frontend/`, `src/backend/`, `src/mcp_server/` only | -| **PyLint** | Push/PR + Paths | Python code linting and quality checks (backend only) | `src/backend/` Python files, requirements.txt, .flake8 config | -| **CodeQL** | Push/PR + Paths + Schedule | Security and code quality analysis | Source code files only (Python, JS, TS, TSX), test Python files | -| **Test Workflow with Coverage** | Push/PR + Paths | Python unit tests with coverage reporting (backend-focused) | Backend, MCP, tests Python files, backend requirements | -| **Test Automation** | Push/PR + Paths + Manual | Run automated tests | Python files, test files, requirements | -| **Validate Deployment** | Push/PR + Paths + Schedule + Manual | Infrastructure validation and deployment | Main Bicep template, modules, parameters, infra scripts only | -| **Broken Link Checker** | PR + Paths + Manual | Check documentation links | Markdown files | - ---- - -## Detailed Workflow Documentation - -### 1. Docker Build and Push (`docker-build-and-push.yml`) - -**Purpose**: Builds and optionally pushes Docker images for the three main components of the application. - -**When it runs**: -- **Push** to branches: `main`, `dev-v3`, `demo-v3`, `hotfix` -- **Pull Requests** targeting these branches -- **Manual trigger** (`workflow_dispatch`) - -**Path Filters** - Only runs when these files change: -```yaml -- 'src/frontend/**' # Frontend React application -- 'src/backend/**' # Python backend API -- 'src/mcp_server/**' # MCP (Model Context Protocol) server -- '.github/workflows/docker-build-and-push.yml' # This workflow file -``` - -**What it does**: -1. Builds three Docker images: `macaebackend`, `macaefrontend`, `macaemcp` -2. Pushes images to Azure Container Registry (ACR) when on protected branches -3. Tags images with branch-specific tags and historical tags -4. Skips push for pull requests (build-only validation) - -### 2. Python Linting (`pylint.yml`) - -**Purpose**: Ensures Python code quality and adherence to coding standards using Flake8. - -**When it runs**: -- **Push** to any branch -- **Pull Requests** to any branch - -**Path Filters** - Only runs when these files change: -```yaml -- 'src/backend/**/*.py' # Backend Python files (only files actually linted) -- 'src/backend/requirements.txt' # Backend dependencies (only file actually installed) -- '.flake8' # Flake8 configuration (only config file actually used) -- '.github/workflows/pylint.yml' # This workflow file -``` - -**What it does**: -1. Sets up Python 3.11 environment -2. Installs dependencies from backend requirements -3. Runs Flake8 linting on the backend code - -### 3. CodeQL Code Scanning (`codeql.yml`) - -**Purpose**: Performs security and code quality analysis using GitHub's CodeQL engine. - -**When it runs**: -- **Push** to branches: `main`, `dev`, `demo` -- **Pull Requests** targeting these branches -- **Scheduled** runs: Every Tuesday at 8:44 PM UTC - -**Path Filters** - Only runs when these files change: -```yaml -- 'src/**/*.py' # All Python source code files -- 'src/**/*.js' # All JavaScript source code files -- 'src/**/*.ts' # All TypeScript source code files -- 'src/**/*.tsx' # All TypeScript JSX source code files -- 'tests/**/*.py' # Python test files only (no .jsx files exist) -- '.github/workflows/codeql.yml' # This workflow file -``` - -**What it does**: -1. Analyzes JavaScript/TypeScript and Python code -2. Identifies security vulnerabilities and code quality issues -3. Creates alerts for any findings -4. Runs automatically on schedule for continuous monitoring - -### 4. Test Workflow with Coverage (`test.yml`) - -**Purpose**: Runs Python unit tests with coverage reporting for code quality assurance (backend-focused). - -**When it runs**: -- **Push** to branches: `main`, `dev`, `demo`, `hotfix` -- **Pull Requests** targeting these branches - -**Path Filters** - Only runs when these files change: -```yaml -- 'src/backend/**/*.py' # Backend Python files (actually tested) -- 'src/tests/**/*.py' # Source test files (actually tested) -- 'src/mcp_server/**/*.py' # MCP server Python files (actually tested) -- 'pytest.ini' # Pytest configuration -- 'conftest.py' # Pytest configuration -- 'src/backend/requirements.txt' # Backend requirements (actually installed) -- 'pyproject.toml' # Python project configuration -- '.github/workflows/test.yml' # This workflow file -``` - -**What it does**: -1. Sets up Python environment -2. Installs dependencies from requirements files -3. Runs unit tests with pytest -4. Generates code coverage reports -5. Validates code quality metrics - -### 5. Test Automation (`test-automation.yml`) - -**Purpose**: Runs automated end-to-end tests against deployed instances. - -**When it runs**: -- **Push** to any branch -- **Pull Requests** to any branch -- **Manual trigger** (`workflow_dispatch`) -- **Called by other workflows** (`workflow_call`) - -**Path Filters** - Only runs when these files change: -```yaml -- 'src/**/*.py' # All Python source files -- 'tests/**' # All test files -- 'src/tests/**' # Source test files -- 'pytest.ini' # Pytest configuration -- 'conftest.py' # Pytest configuration -- 'requirements*.txt' # Any requirements files -- 'src/backend/requirements*.txt' # Backend requirements -- 'src/mcp_server/requirements*.txt' # MCP server requirements -- '.github/workflows/test-automation.yml' # This workflow file -``` - -**What it does**: -1. Sets up Python 3.13 environment -2. Authenticates with Azure -3. Runs automated tests against deployed MACAE instances -4. Can be configured with various test parameters - -### 6. Validate Deployment (`deploy.yml`) - -**Purpose**: Validates Azure infrastructure and performs deployments. - -**When it runs**: -- **Push** to branches: `main`, `dev-v3`, `hotfix` -- **Pull Requests** targeting these branches -- **After successful Docker builds** (`workflow_run`) -- **Scheduled** runs: Daily at 11:00 AM and 11:00 PM GMT -- **Manual trigger** (`workflow_dispatch`) - -**Path Filters** - Only runs when these files change: -```yaml -- 'infra/main.bicep' # Main Bicep template (actually used) -- 'infra/modules/**/*.bicep' # Bicep module files (actually used) -- 'infra/*.parameters.json' # Parameter files (actually used) -- 'infra/scripts/**' # Infrastructure scripts (actually used) -- '.github/workflows/deploy.yml' # This workflow file -``` - -**What it does**: -1. Checks Azure quota requirements -2. Creates or validates resource groups -3. Deploys Bicep templates to Azure -4. Configures deployed resources -5. Runs end-to-end tests -6. Cleans up resources if configured - -### 7. Broken Link Checker (`broken-links-checker.yml`) - -**Purpose**: Validates links in documentation files. - -**When it runs**: -- **Pull Requests** (any branch) -- **Manual trigger** (`workflow_dispatch`) - -**Path Filters** - Only runs when these files change: -```yaml -- '**/*.md' # All Markdown files -``` - -**What it does**: -1. Scans all Markdown files for links -2. Validates that links are accessible -3. Reports any broken links found - ---- - -## Workflow Dependencies - -```mermaid -graph TD - A[Docker Build & Push] --> B[Validate Deployment] - B --> C[Test Automation] - D[PyLint] --> E[Code Quality Gate] - F[CodeQL] --> E - E --> G[Deployment Approval] -``` - -### Dependency Chain: -1. **Code Quality Checks** (PyLint, CodeQL) run independently -2. **Docker Build & Push** must complete successfully -3. **Validate Deployment** triggers after successful Docker builds -4. **Test Automation** runs as part of deployment validation - ---- - -## Branch-Specific Behavior - -### Protected Branches (`main`, `dev-v3`, `demo-v3`, `hotfix`) -- Docker images are **pushed** to ACR -- Full deployment validation occurs -- Scheduled workflows run -- All quality gates must pass - -### Feature Branches -- Docker images are **built only** (not pushed) -- Deployment validation skipped -- Code quality checks still run -- Faster feedback loop for development - -### Pull Requests -- All path-filtered workflows run for validation -- No deployment or image pushing occurs -- Provides comprehensive validation before merge - ---- - -## Path Filter Benefits - -### Performance Optimization -- **Reduced CI/CD time**: Only relevant workflows run -- **Lower resource usage**: No unnecessary job executions -- **Faster feedback**: Developers get quicker PR status updates -- **Optimized triggers**: Paths are precisely matched to what each workflow actually uses - -### Clearer PR Status -- PR checks only show relevant pipeline results -- Easier to identify which changes need attention -- Reduced noise from unrelated workflow failures - -### Recent Optimizations (December 2025) -All workflow path filters have been optimized to only include files that are actually used by each workflow: - -- **Docker Build & Push**: Removed unused Dockerfile patterns, requirements files, and lock files not in source directories -- **PyLint**: Streamlined to only backend Python files, specific requirements.txt, and .flake8 config (workflow only lints backend) -- **CodeQL**: Removed non-existent .jsx files, focused on actual source code files -- **Test Workflow**: Aligned with backend-focused testing approach, removed unused requirements patterns -- **Validate Deployment**: Removed unused custom templates and Azure config files not referenced by workflow - -**Result**: Significantly reduced false triggers from files like `.env.sample`, documentation changes, or configuration files that don't affect specific workflows. - -### Examples of Path-Based Triggering - -| Change Type | Workflows That Run | -|-------------|-------------------| -| Update React component in `src/frontend/` | Docker Build & Push, CodeQL | -| Modify Python API in `src/backend/` | Docker Build & Push, PyLint, CodeQL, Test with Coverage | -| Update MCP server in `src/mcp_server/` | Docker Build & Push, CodeQL, Test with Coverage | -| Update main Bicep template in `infra/main.bicep` | Validate Deployment | -| Update `.flake8` configuration | PyLint | -| Edit `.env.sample` files | **No workflows run** (optimized out) | -| Update documentation in `docs/` | Broken Link Checker (if .md files) | -| Update GitHub workflow file | The specific workflow + any dependent workflows | - ---- - -## Manual Workflow Triggers - -All workflows support manual triggering through the GitHub Actions UI: - -1. Go to **Actions** tab in GitHub -2. Select the desired workflow -3. Click **Run workflow** -4. Choose branch and provide any required inputs - -### Workflows with Additional Inputs -- **Validate Deployment**: Various Azure configuration options -- **Test Automation**: Test parameters and environment settings - ---- - -## Troubleshooting - -### Workflow Not Running When Expected -1. **Check path filters**: Ensure your changes match the path patterns -2. **Verify branch targeting**: Some workflows only run on specific branches -3. **Review workflow file**: Check for syntax errors in YAML - -### All Workflows Running Despite Path Filters -- Workflows always run when their own file (`.yml`) is modified -- Changes to root-level configuration files may trigger multiple workflows -- Manual triggers bypass path filtering - -### Performance Issues -- Path filters are working correctly if you see fewer workflow runs -- Check workflow run history to verify optimal triggering -- Contact maintainers if you notice performance degradation - ---- - -## Maintenance - -### Adding New Path Filters -1. Identify which files should trigger the workflow -2. Update the `paths:` section in the workflow YAML -3. Test with a sample PR to verify correct behavior -4. Update this documentation - -### Modifying Existing Filters -1. Consider impact on existing development workflows -2. Test changes in a feature branch first -3. Update documentation to reflect changes -4. Communicate changes to the development team - -For questions or issues with GitHub Actions workflows, please refer to the [troubleshooting guide](TroubleShootingSteps.md) or create an issue in this repository. \ No newline at end of file