stabilize tests
This commit is contained in:
master
109
devops/ci-local/README.md
Normal file
109
devops/ci-local/README.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user