From 46df241f7d38c1f2d505c8557042898cf7faa3f0 Mon Sep 17 00:00:00 2001
From: Bruno Domingues <bruno.domingues@aignosi.com.br>
Date: Tue, 2 Dec 2025 17:28:04 -0300
Subject: [PATCH] SIENTIAPDE-1352: Add documentation for local GitHub Actions
 testing with act.

This commit adds a new section to the README.md file detailing how to use the 'act' tool for local testing of GitHub Actions workflows. It includes installation instructions, configuration details, usage examples, and troubleshooting tips.
---
 README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)

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