stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
5d5e80b2e443d61f74451920405b4e894ef28b4e
git.stella-ops.org/devops/ci-local/README.md
master 5d5e80b2e4 stabilize tests
2026-02-01 21:37:40 +02:00

4.6 KiB
Raw Blame History

Local CI with act

Run Gitea CI workflows on your machine using nektos/act and the StellaOps CI Docker image.

Prerequisites

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
act -W .gitea/workflows/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

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:

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