git.stella-ops.org/devops/ci-local/README.md

# 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 (archived workflows)
act -W .gitea/workflows-archived/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
```

## Gitea CI verification pipeline

The `local-ci-verify.yml` workflow (in `.gitea/workflows/`) provides a one-click
way to validate your local CI setup from within Gitea Actions itself.

**Trigger:** Manual dispatch only (Gitea UI: **Actions > Local CI Verification > Run workflow**).

**Inputs:**
| Input | Default | Description |
|-------|---------|-------------|
| `workflow` | _(empty)_ | Archived workflow file to dry-run (e.g. `test-matrix.yml`) |
| `dry_run` | `true` | Pass `-n` (dry-run) to act |

**Jobs:**
1. **validate-scaffolding** — Checks that all `devops/ci-local/` files exist and event JSON is valid.
2. **build-ci-image** — Builds `stellaops-ci:local` from `devops/docker/Dockerfile.ci`.
3. **dry-run-smoke** — Runs `act -l` and `act -n` against `test-matrix.yml` from the archive, plus an optional user-specified workflow.

**API trigger example:**

```bash
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  "https://git.stella-ops.org/api/v1/repos/<org>/<repo>/actions/workflows/local-ci-verify.yml/dispatches" \
  -d '{"ref":"main","inputs":{"workflow":"test-matrix.yml","dry_run":"true"}}'
```

## Common workflows

> **Note:** Workflows have been archived to `.gitea/workflows-archived/`. The
> paths below reflect the archive location.

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