ci

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

Ze's CI runs the same Make targets that you run locally, so that "works locally" and "passes CI" are the same statement. CI runs on GitHub Actions, and the workflows live in the repository under .github/workflows/. Validation previously ran on Codeberg's shared Woodpecker runners; that pipeline is gone.

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

The workflows

Workflow	Trigger	What it runs
verify.yml	Every push and pull request	make ze-verify. The merge gate.
govulncheck.yml	Nightly, plus manual	make ze-vulncheck. Dependency vulnerability scan.
evidence-nightly.yml	Nightly, plus manual	Fuzz and kernel integration suites. Advisory.
perf-nightly.yml	Nightly, plus manual	Performance benchmarks.
codeql.yml	Scheduled and on push	CodeQL static analysis across the shipped build-tag combinations.
pages.yml	On push	Documentation site build.

What gates a merge

verify.yml runs make ze-verify and nothing else. The stage list is deliberately not duplicated in the workflow: it lives in stagesForMode (scripts/status/verify_run.go) and nowhere else, so a gate missing from that function runs nowhere. Read the live list with make ze-verify-list.

That single-source arrangement is the point. Adding a check to the Makefile is not enough; it has to be in the stage list to actually gate anything.

What runs on a schedule instead

Three kinds of work are kept off the merge path.

Vulnerability scanning. make ze-vulncheck runs govulncheck against the Go vulnerability database and reports issues reachable from Ze's own call graph. It is scheduled rather than blocking on purpose: the scan fetches the vulnerability database over the network, and neither a transient fetch failure nor a newly published advisory should wedge the merge gate. The always-on supply-chain guard that does gate merges is the vendored-updater fix-marker test in the unit suite.

Heavy evidence. Fuzz targets and the kernel integration suites need root and CAP_NET_ADMIN, so they run nightly on a runner that has them, and each job is advisory. ze-qemu-integration-test stays out: it needs nested virtualisation that GitHub-hosted runners do not reliably provide, and a pipeline that cannot start catches nothing.

Everything else on demand.

• make ze-mutation-test / make ze-mutation-changed. Mutation testing via gomu. Advisory only. See Testing.
• make ze-interop-test. Docker-based interop against FRR, BIRD, GoBGP.
• make ze-live-test. Live BGP tests against real RPKI caches and looking glasses.
• make ze-stress-test. Long-duration stress runs.

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 thorough target: lint, changed-file wiring and doc gates, unit tests, functional tests, and ExaBGP. It is what the merge gate runs and what you should run before submitting. ze-ci is lighter (lint, unit tests, build) and is useful as a quick local sanity check.

make ze-verify        # What CI runs: lint, static gates, unit, functional, ExaBGP
make ze-verify-list   # The live stage list
make ze-ci            # Quick local 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. 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.