Skip to main content
Every check is one make target. CI runs exactly that target, so a check that fails in CI fails the same way on a workstation. This page covers how that is enforced and what each job proves.

Three rules every job follows

  1. Everything is pinned in one file. pins.toml names every version the kit builds against or tests: stellar-core 30.0.0 (commit, .deb sha256, binary sha256, image digests), the XDR definitions tag v30.0, rs-stellar-xdr 30.0.0, the Go, Rust, Node and Python toolchains, every SDK column, wallet-backend’s commits, stellar-etl v2.8.35, and the SeaweedFS and TimescaleDB images by digest. xdrcheck pins check fails when a version is named anywhere else (a lock file, a toolchain file, a Dockerfile, a constant in the code) or differs from the pin. It also reads the dated [[schedule]] events (the mainnet vote on Protocol 30 on 2026-11-23, the testnet reset on 2026-12-16) and fails once an event’s day has passed and its pin has not moved.
  2. One networked step: make fetch. It downloads everything into caches, each item checked by hash. It is split into parts (scripts/fetch.sh), and a job fetches only the parts its target reads with make fetch FETCH_ONLY="…": Source: docs/ci-timings.md, “Fetch parts”.
  3. Every check runs with the network cut. make <target> OFFLINE=1 wraps the run in scripts/offline-run.sh: unshare --user --map-root-user --net --mount, a private network namespace with only loopback up, and name lookups cut too (/etc/resolv.conf bind-mounted empty, /run/systemd/resolve hidden). Where user namespaces are not allowed, XDRCHECK_OFFLINE_FALLBACK=docker runs the command in a pinned container with --network none. Inside the namespace, wallet-backend’s TimescaleDB runs in a container with --network none reached through a Unix socket, and the S3 store runs as the pinned image’s own weed binary. A check that tries to download something fails.

The two tiers

Both tiers run on GitHub’s standard runners (2 vCPUs, 7.7 GiB), with permissions: contents: read and no secrets. The build job runs make build once (itself under offline-run.sh) and hands the tools to the other jobs as an artifact.

Pull-request CI (.github/workflows/pr.yml)

Trigger: every pull request, every push to a branch other than main, and by hand. Locally: make verify-pr. Measured: about 15 minutes with warm caches, 25 cold; the longest path is P4a (docs/ci-timings.md, measured 2026-11-19).

Full CI (.github/workflows/full.yml)

Trigger: by hand (workflow_dispatch) and on v* release tags. No schedule and no run on a push. Locally: make verify plus the full-size targets below. It runs P0 to P4 and P10, P11 as above (P4 at full size: make test-rust with XDRCHECK_REQUIRE_CORE=1, so the tests that run stellar-core cannot skip), and adds: Times: README.md, “Check every claim yourself” (jobs on a 2-CPU GitHub runner); about 40 minutes wall time with jobs side by side. The local emulation of both tiers from cold caches (make ci-local, 2 CPUs, 7 GiB per job) is in docs/ci-timings.md.

Manual workflows

None of these gates a pull request, and none has a schedule.

Release artifacts

release.yml (on a vMAJOR.MINOR.PATCH tag, or by hand as a dry run) produces one workflow artifact:
  • xdrcheck-<version>.tar.gz: the corpus with SHA256SUMS and PROVENANCE.json (xcc.release/v1: source commit, pins, entry counts, tool versions). Built from git archive <commit>, with fixed timestamps, owners and modes, tar --sort=name and gzip -n -9; make release builds it twice and requires identical bytes.
  • the npm package of the corpus;
  • prebuilt binaries for linux-amd64, linux-arm64, darwin-amd64 and darwin-arm64;
  • SHA256SUMS over the assets, and a container image smoke test.
The corpus version’s MAJOR is the highest protocol it covers (30.y.z covers Protocol 30), so a consumer pinned to ^30.0.0 never receives the Protocol 31 release by accident. A -next channel (31.0.0-rc.N) carries the next protocol’s shapes before it ships (Protocol upgrades).

In your own CI

action.yml is a composite GitHub Action with three modes: replay (your indexer through your adapter), conform (your SDK’s drivers) and lint (xdrlint, with SARIF output). It downloads the prebuilt tools and the corpus of one pinned release and checks them against the release’s SHA256SUMS (optionally against a sha256 of that file you pin in your own repository) before anything runs. Without the action, an SDK uses a loader and an expected-failure list (Conformance). Guides: CI recipes, GitHub Action, CI timings.

Limits

  • The full CI runs by hand and on tags only; a push to main runs neither tier.
  • The golden emission proof (N2) takes about 21 minutes on 8 CPUs and is not part of the full CI.
  • The release provenance is not signed yet.