ci

Pre-Alpha. This page describes behavior that may change.

Ze's CI runs the same Make targets that you run locally. make ze-ci is the CI check and it exists specifically so that "works locally" and "passes CI" are the same statement. The CI configuration is not currently stored in the repository (it is managed externally).

This page covers what actually runs when you push a branch, what to expect, and what to do when it fails.

What runs

make ze-ci runs three things: lint, unit tests, and build.

Lint. make ze-lint. If the lint fails, nothing else runs.

Unit tests. make ze-unit-test. Fast. If this fails, the rest of the pipeline still runs because unit test failures often point at orthogonal bugs.

Build. make build. Verifies that the binaries compile cleanly.

What does not run in CI automatically

A few suites are optional because they are slow or require external services.

• make ze-interop-test. Docker-based interop against FRR, BIRD, GoBGP. Runs on a nightly schedule, not on every PR.
• make ze-live-test. Live BGP tests against real RPKI caches and looking glasses. Runs on demand.
• make ze-stress-test. Long-duration stress runs. Runs on demand.
• make ze-perf. Performance benchmarks. Runs on demand before releases.

Ask the maintainer to run these if your change touches the relevant area.

How to read a failing CI run

The first thing to look at is whether the failure happened before or after make ze-lint. If lint failed, the run did not get far enough to run tests, and the fix is in the lint output.

If the failure is in a unit test, the test output names the package and the test. go test output is not the friendliest, but the structure is predictable. Look for the --- FAIL: lines.

If the failure is in a functional test, the runner prints a diff between the expected output and the actual output. Look at the diff first: most functional failures are either "encoder produced different bytes" (real bug) or "expected output is stale" (the .ci file needs updating).

If the failure is in a fuzz test, the fuzzer saved a reproducer under testdata/fuzz/<target>/. Add it to your local corpus, reproduce it, fix the parser, and commit the reproducer alongside the fix.

Reproducing CI failures locally

The whole pipeline runs from Make. The same Make target will reproduce the same failure locally.

make ze-lint          # Reproduce the lint failure
make ze-unit-test     # Reproduce the unit failure
make ze-functional-test
make ze-fuzz-test

If something passes locally and fails in CI, the usual culprit is a flaky test. Rerun the specific test with --count 10 to make the flake visible.

ze-test bgp encode --count 10 <test-nick>

A test that passes nine out of ten times is a bug, not a flake. Find the race, fix it, do not mark the test as "known flaky".

make ze-verify vs make ze-ci

These are close but not identical. ze-verify is the more thorough pre-commit target you run on your development machine: it runs lint, unit tests, functional tests, and ExaBGP tests. ze-ci is lighter: it runs lint, unit tests, and build. Use ze-verify to catch more problems before submission; ze-ci is the quick sanity check that CI runs.

make ze-verify        # Thorough pre-commit check: lint, unit, functional, ExaBGP
make ze-ci            # CI check: lint, unit tests, build

make ze-verify-changed is the finest-grained iteration target: it only runs ze-verify on the packages your branch has touched. Use it on every save during development.

Doc drift

make ze-doc-drift

ze-doc-drift scans the in-tree documentation for claims that no longer match the code: a flag that was removed, a command name that changed, a plugin that is no longer shipped. It runs in CI on schedule rather than on every PR, because some documentation updates land separately from the code. If your change renames a flag or moves a command, run this target locally and fix whatever it surfaces.

When the build fails for no obvious reason

If a build fails and the failure does not come from your changes:

1. Pull the latest main and rebase.
2. make clean and rebuild from scratch.
3. Check if the vendored third-party code is out of sync (make ze-check-vendor-web).
4. Check if there is a known issue in the maintainer's status.

If none of those fix it, ask the maintainer. It is often faster than debugging CI flakes alone.

See also

• Building for the Make targets.
• Testing for what the test targets actually do.
• Contributing for the pre-submission checklist.

Adapted from main/docs/ci-test-coverage.md and main/Makefile.