Testing and CI

Testing and CI

Before committing

Install just and start Docker before running lightweight tests. On macOS, Docker Desktop provides the Docker engine; install just with your package manager, for example brew install just.

Run these checks from the project root:

just check-worktree
just test-lightweight

just check-worktree runs YAML linting and Ansible syntax validation. It checks untracked files too, which catches a newly created YAML file before it reaches Git.

Test commands

Command	Purpose
just check	YAML lint and Ansible syntax checks.
just check-worktree	Same checks, including untracked files.
just test-bootstrap-lightweight	Creates an SSH container, runs bootstrap twice, verifies SSH and sudo.
just test-setup-lightweight	Renders and validates SSH, iptables, Docker, and Traefik fixtures.
just test-lightweight	Runs both lightweight tests.
just test-bootstrap-heavy	Full bootstrap test in a Lima VM on macOS.
just test-setup-heavy	Full setup and SSH migration test in a Lima VM on macOS.
just test-heavy	Runs both heavy tests.
just test	Runs lightweight and heavy suites.

Ubuntu test targets

CI runs both lightweight suites on GitHub-hosted Ubuntu 22.04, 24.04, and 26.04 runners. The test scripts also pass the selected version into their Docker fixture image.

Run one target locally:

TEST_UBUNTU_VERSION=22.04 just test-lightweight
TEST_UBUNTU_VERSION=24.04 just test-lightweight
TEST_UBUNTU_VERSION=26.04 just test-lightweight

The production provisioning guide remains Ubuntu 24.04. The matrix proves lightweight compatibility coverage, not a promise that every production role is supported on every version.

OpenSpec

openspec/specs/ is the versioned architecture baseline. It records the current required behavior for managed access, the host baseline, the edge proxy, application delivery, and validation.

Read the relevant spec before changing a service contract. Create an OpenSpec change proposal before altering any of these:

• network exposure, firewall ports, or SSH access;
• secrets or persistent data;
• public services, ACME, or Traefik routing;
• a provisioning migration or its ordering.

Install the CLI and validate all OpenSpec artifacts locally:

npm install --global @fission-ai/openspec@1.10.0
openspec validate --all --strict

The pre-commit validation runs only when a file below openspec/ changes. CI uses the same path condition. An OpenSpec-only change runs its validation job without starting the six Ubuntu matrix test jobs; a mixed change runs both.

Heavy tests

Heavy tests require macOS and Lima:

brew install lima
just test-heavy

The setup-heavy test checks SSH migration from 22571 to 22572, idempotence, installed tools, active Docker and CrowdSec services, the running Traefik container, and firewall policy.

Disposable Yandex Cloud VM

For a real Ubuntu 24.04 smoke test, configure the Yandex Cloud CLI and provide a subnet name and public SSH key:

YC_TEST_VM_SUBNET=default-ru-central1-a \
YC_TEST_VM_SSH_KEY="$HOME/.ssh/id_ed25519.pub" \
just test-yc-vm-create

The recipe creates a VM with 2 vCPUs, 2 GB memory, a 20 GB network SSD boot disk, and public IPv4. It records the VM ID in ignored .test-yc-vm-id.

Delete the exact recorded VM when finished:

just test-yc-vm-delete

Do not delete .test-yc-vm-id until the VM is deleted. The cleanup recipe uses that file as its only target selection.

CI workflows

• Lint runs uv sync --group dev --frozen, yamllint, and Ansible syntax checks on pushes and pull requests.
• Checks runs Bootstrap and Setup lightweight test matrices on Ubuntu 22.04, 24.04, and 26.04.

Conventional commits

Commit messages must match Conventional Commits. Examples:

fix(crowdsec): reconcile acquisitions
ci: split lint and matrix test workflows

The accepted types are build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test.