diff --git a/README.md b/README.md
index 65884e4..974ca62 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,12 @@ An enterprise-grade ML model training orchestration platform built on Temporal.
   - [Code Quality Standards](#code-quality-standards)
 - [License](#license)
 - [Support](#support)
+- [Local GitHub Actions Testing (act)](#local-github-actions-testing-act)
+  - [What is act?](#what-is-act)
+  - [Installation](#installation)
+  - [Configuration](#configuration-2)
+  - [Usage](#usage)
+  - [Command Reference](#command-reference)
 - [Docker](#docker)
 - [Helm Chart](#helm-chart)
 
@@ -1172,6 +1178,150 @@ For support and questions:
 - Open an issue in the project repository
 - Contact the development team
 
+## Local GitHub Actions Testing (act)
+
+### What is act?
+
+[act](https://nektosact.com/) is a tool that allows you to run GitHub Actions locally using Docker. This is useful for:
+
+- **Testing workflows** before pushing to the repository
+- **Debugging issues** in workflows without creating commits
+- **Speeding up development** by avoiding push/wait/check cycles
+- **Saving GitHub Actions minutes** during development
+
+### Installation
+
+#### Prerequisites
+
+- Docker installed and running
+- Go (for installation via `go install`)
+
+#### Installation Steps
+
+```bash
+# 1. Update packages
+sudo apt-get update
+
+# 2. Install Go (if not already installed)
+sudo apt-get install golang
+
+# 3. Install act
+go install github.com/nektos/act@latest
+
+# 4. Add Go bin to PATH
+echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
+source ~/.bashrc
+
+# 5. Verify installation
+act --version
+```
+
+On first run, `act` will ask which Docker image to use:
+- **Large** (~17GB): Full image, compatible with almost all actions
+- **Medium** (~500MB): Balanced image, compatible with most actions ✅ Recommended
+- **Micro** (<200MB): Minimal image, Node.js only
+
+### Configuration
+
+#### `.secrets` File
+
+Create a `.secrets` file in the project root to store tokens and credentials:
+
+```bash
+# .secrets
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+SONAR_TOKEN=sqp_xxxxxxxxxxxxxxxxxxxx
+SONAR_HOST_URL=https://sonarqube.example.com
+APP_ID=123456
+APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
+```
+
+> ⚠️ **Important**: The `.secrets` file is already in `.gitignore`. Never commit this file!
+
+#### `.event.json` File
+
+Create a `.event.json` file to simulate GitHub events (e.g., pull request):
+
+```json
+{
+  "pull_request": {
+    "head": {
+      "ref": "feature/my-feature"
+    },
+    "number": 1
+  }
+}
+```
+
+> ⚠️ **Important**: The `.event.json` file is already in `.gitignore`. Never commit this file!
+
+### Usage
+
+#### List Available Jobs
+
+```bash
+act -l
+```
+
+This command lists all available workflows and jobs in the repository.
+
+#### Run Quality Gate Locally
+
+```bash
+act pull_request -j quality-gate \
+  --secret-file .secrets \
+  --env SONAR_SCANNER_OPTS="-Dsonar.ci.autoconfig.disabled=true" \
+  --eventpath .event.json
+```
+
+### Command Reference
+
+#### Command Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `pull_request` | Event type to simulate (can be `push`, `pull_request`, `workflow_dispatch`, etc.) |
+| `-j quality-gate` | Specific job name to execute (use `act -l` to see available jobs) |
+| `--secret-file .secrets` | File containing secrets (tokens, credentials) |
+| `--env VAR=value` | Sets environment variables for execution |
+| `--eventpath .event.json` | JSON file with the simulated event payload |
+
+#### Special Parameter: `SONAR_SCANNER_OPTS`
+
+```bash
+--env SONAR_SCANNER_OPTS="-Dsonar.ci.autoconfig.disabled=true"
+```
+
+This parameter is required because SonarQube tries to automatically detect the CI environment. When running locally with `act`, the complete GitHub Actions context is not available, causing errors. The `-Dsonar.ci.autoconfig.disabled=true` flag disables this automatic detection.
+
+#### Other Useful Commands
+
+```bash
+# List all jobs
+act -l
+
+# Run with verbose output
+act pull_request -j quality-gate --secret-file .secrets -v
+
+# Run a push event
+act push -j build --secret-file .secrets
+
+# Use a specific Docker image
+act -P ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Dry-run (doesn't execute, only shows what would be done)
+act -n
+```
+
+#### Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `SyntaxError: Unexpected end of JSON input` | Check if `.event.json` is properly formatted |
+| `NullPointerException` in SonarQube | Add `--env SONAR_SCANNER_OPTS="-Dsonar.ci.autoconfig.disabled=true"` |
+| `Not Found` when accessing GitHub API | Check if `GITHUB_TOKEN` in `.secrets` is valid |
+| Job not found | Use `act -l` to see the correct job names |
+
 ## Docker
 
 ### Create image