110 lines
4.6 KiB
Markdown
110 lines
4.6 KiB
Markdown
# 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
|
|
```
|