Tool	Install
Docker Desktop	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

# 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)

.\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

./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:

./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:

validate-scaffolding — Checks that all devops/ci-local/ files exist and event JSON is valid.
build-ci-image — Builds stellaops-ci:local from devops/docker/Dockerfile.ci.
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:

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:

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:

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