Skip to content
binder

CI usage

validate is the CI gate: on a well-formed run it exits non-zero only on a hard conformance violation, and under --strict also on advisories (see the exit-code contract). The gate covers concept files; reserved-file structure is outside its scope. See validate. A typical pipeline converts, then validates:

Terminal window
set -euo pipefail


SOURCE_DATE_EPOCH=1700000000 binder convert docs/ -o build/bundle
binder validate build/bundle          # exit 1 on §11 non-conformance fails the job
binder review   build/bundle          # advisory summary (orphans, stale, unresolved)
binder graph    build/bundle --format json -o build/graph.json

For machine consumption, add --json and branch on both the exit code and the parsed payload. The exit code is identical in prose and JSON mode, so a CI step can gate on the code while archiving the JSON as an artifact:

Terminal window
set -euo pipefail


# Gate on the exit code (0 conformant, 1 non-conformant, 2 usage, 3 io);
# archive the deterministic JSON report either way.
if binder validate build/bundle --json > build/validate.json; then
  echo "conformant"
else
  code=$?
  echo "validate exited $code"        # 1 = non-conformant, 2/3 = usage/io
  jq '.result.findings[] | select(.severity=="error")' build/validate.json
  exit "$code"
fi


# lint the SOURCE corpus before conversion; --strict gates on any finding.
binder lint    docs/ --strict                   # fail on broken links / orphans / …


# review is advisory by default; --strict makes it (and convert) gate.
binder convert docs/ -o build/bundle --strict   # fail on unresolved links / recoveries
binder review  build/bundle --strict            # fail on orphans / stale / unresolved

By default review and graph never fail the build (they always exit 0); use them for reporting and artifacts. To fail a build on unresolved links, orphans, or staleness, pass --strict to convert, review, lint, or validate; it promotes those advisories to gating findings (exit 1) for that run only. binder lint gates on source-corpus health before conversion; the others gate on the emitted bundle.

The project’s own exit gate additionally cross-checks binder’s verdicts against the external okfcli/okf validator in both directions (make gate); see Differential-validation exit gate.