# Local CI with act

Run Gitea CI workflows on your machine using [nektos/act](https://github.com/nektos/act) and the StellaOps CI Docker image.

## Prerequisites

| Tool | Install |
|------|---------|
| Docker Desktop | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
| act | **Windows:** `choco install act-cli` / **macOS:** `brew install act` / **Linux:** `curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh \| sudo bash` |

Docker must be running before you invoke any command below.

## Quick start

```bash
# 1. Build the CI image (one-time, ~10 min first build)
docker build -t stellaops-ci:local -f devops/docker/Dockerfile.ci .

# 2. Copy the env template (edit as needed)
cp devops/ci-local/.env.local.template devops/ci-local/.env.local

# 3. List available jobs
act -l

# 4. Dry-run a workflow
act -W .gitea/workflows/test-matrix.yml -n
```

### Windows (PowerShell)

```powershell
.\devops\ci-local\run-act.ps1 -List
.\devops\ci-local\run-act.ps1 -Workflow test-matrix -DryRun
.\devops\ci-local\run-act.ps1 -Workflow build-test-deploy -Job build
```

### Linux / macOS

```bash
./devops/ci-local/run-act.sh --list
./devops/ci-local/run-act.sh --workflow test-matrix --dry-run
./devops/ci-local/run-act.sh --workflow build-test-deploy --job build
```

### Full-featured runner (bash only)

The `local-ci.sh` script supports additional modes beyond raw act invocation:

```bash
./devops/scripts/local-ci.sh smoke                        # Quick unit tests
./devops/scripts/local-ci.sh pr                           # Full PR-gating suite
./devops/scripts/local-ci.sh workflow --workflow test-matrix
./devops/scripts/local-ci.sh module --module Scanner
```

## Common workflows

| Workflow | What it tests | Example |
|----------|--------------|---------|
| `test-matrix.yml` | Unit + integration test matrix | `act -W .gitea/workflows/test-matrix.yml -n` |
| `build-test-deploy.yml` | Full build/test/deploy pipeline | `act -W .gitea/workflows/build-test-deploy.yml -n` |
| `scanner-analyzers.yml` | Scanner analyzer suite | `act -W .gitea/workflows/scanner-analyzers.yml -n` |
| `parity-tests.yml` | Cross-platform parity checks | `act -W .gitea/workflows/parity-tests.yml -n` |
| `integration-tests-gate.yml` | Integration test gate | `act -W .gitea/workflows/integration-tests-gate.yml -n` |
| `schema-validation.yml` | JSON/OAS schema validation | `act -W .gitea/workflows/schema-validation.yml -n` |
| `determinism-gate.yml` | Deterministic output checks | `act -W .gitea/workflows/determinism-gate.yml -n` |

## Environment variables

See `.env.local.template` for the full list. Key variables:

| Variable | Default | Purpose |
|----------|---------|---------|
| `STELLAOPS_TEST_RABBITMQ` | `0` | Set `1` to enable RabbitMQ tests |
| `STELLAOPS_TEST_VALKEY` | `0` | Set `1` to enable Valkey/Redis tests |
| `STELLAOPS_INTEGRATION_TESTS` | `false` | Enable integration test suite |
| `STELLAOPS_LIVE_TESTS` | `false` | Enable network-dependent tests |
| `STELLAOPS_SOFTHSM_LIB` | _(empty)_ | Path to SoftHSM2 library for HSM tests |
| `STELLAOPS_TEST_POSTGRES_CONNECTION` | _(empty)_ | External Postgres (Testcontainers auto-configure if empty) |

## Known limitations

- **Services block:** `act` does not natively support `services:` blocks in workflow YAML. Workflows that declare Postgres/Valkey/RabbitMQ services will need those services running externally (use `docker-compose.testing.yml`).
- **Secrets:** GitHub/Gitea-style secrets are not available locally. Use `.env.local` for test-only values. Never put production secrets in `.env.local`.
- **Artifact upload:** `act` provides a local artifact server (`--artifact-server-path ./out/act-artifacts`). Upload/download actions work but paths differ from real CI.
- **Composite actions:** Some nested composite actions may not resolve correctly under act.

## Troubleshooting

### Docker socket on Windows / WSL
If act cannot connect to Docker, ensure Docker Desktop has "Expose daemon on tcp://localhost:2375 without TLS" enabled, or use WSL 2 integration.

### OOM with parallel builds
The CI image runs .NET builds that can consume significant memory. If builds fail with OOM, increase Docker Desktop memory allocation (Settings > Resources > Memory) to at least 8 GB.

### MSYS path mangling (Git Bash on Windows)
Git Bash on Windows rewrites Unix-style paths. If act receives corrupted paths, prefix the command with `MSYS_NO_PATHCONV=1`:

```bash
MSYS_NO_PATHCONV=1 act -W .gitea/workflows/test-matrix.yml -n
```

### Container reuse issues
If you see stale state between runs, disable container reuse:

```bash
act --no-reuse -W .gitea/workflows/test-matrix.yml
```