# CI

## Workflows

`.github/workflows/`:

| Workflow | Purpose |
|---|---|
| `ci-code.yml` | Build + unit tests across the Linux distro matrix. |
| `ci-api-docs.yml` | API/plugin docs build check. |

Plus an OpenBSD pipeline at `.builds/openbsd.yml` (sourcehut-style builds).

## Distro matrix

The code CI runs across the Dockerfiles at repo root: Debian, Ubuntu,
Fedora, Tumbleweed, Arch. Each job builds the matching image, mounts the
checkout, and runs `autogen.sh && configure && make && make check`.

## Log naming

CI logs in this project are named:

```
ci-code-Linux (arch)-NNNN.log
```

— where `arch` is the distro flavour (debian, ubuntu, fedora, tumbleweed,
arch) and `NNNN` is the run number. Use the distro name to pick the right
log when triaging matrix failures.

## Known matrix-specific notes

- **Arch (`Dockerfile.arch`):** Pikaur in the image was hit by a duplicated-flag
  failure (cf. cproof commit `0722dc9e3`). If `Dockerfile.arch` changes,
  re-check the Pikaur invocation.
- **OpenBSD (`.builds/openbsd.yml`):** runs on sourcehut, not GitHub. Failures
  there don't appear in the GitHub PR check list.

## Reproducing a CI failure locally

1. Identify the failing distro from the log name.
2. Build the matching Dockerfile locally — see `build/docker.md`.
3. Run the same `autogen && configure && make && make check` chain inside the
   container.
4. Compare versions of any drifting dependency between the image and the CI
   image (`apt list --installed` or equivalent inside both).

## What CI does not run

- Functional tests (`tests/functionaltests/`) — require a test XMPP server.
- Benches (`tests/bench/`) — not part of CI.

If you need either, run them locally inside the Docker image — see
`testing/functional-tests.md` and `testing/bench.md`.