> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xdrcheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CI recipes

> Run XDRCheck in your CI: the GitHub Action for indexers, SDKs and Go linting, expected-failure lists, replaying pinned real ledgers through an SDK branch, and running offline with bounded memory.

For SDK maintainers and indexer teams adding XDRCheck to their own CI. After this page you can pick the job that
fits your code, copy it, keep an expected-failure list, and run the same checks offline on a workstation.

| You want | Use | Section |
| - | - | - |
| Replay the corpus through your indexer on every pull request | the GitHub Action, `mode: replay`, with your adapter and an expected-failure list | [Indexer authors: replay](#2-indexer-authors-replay) |
| Put the corpus through your SDK on every pull request | a recipe in your SDK's own test suite, or the GitHub Action, `mode: conform` | [SDK CI](https://docs.xdrcheck.dev/guides/sdk-ci.md), [SDK maintainers: conform](#3-sdk-maintainers-conform) |
| Lint Go ingestion code | the GitHub Action, `mode: lint` (SARIF for code scanning), or `xdrlint` in a plain step | [Go teams: lint](#5-go-teams-lint), [Lint Go code](https://docs.xdrcheck.dev/guides/lint-go.md) |
| Replay a pinned set of real ledgers through an SDK branch | `xdrcheck data export` once, then `xdrcheck replay --target` against the pinned dataset | [Replay real ledgers in CI](#replay-real-ledgers-in-ci) |
| Test the next protocol's shapes | the `-next` corpus channel | [Protocol upgrade (SDK)](https://docs.xdrcheck.dev/guides/protocol-upgrade-sdk.md) |
| Run the checks with no network and bounded memory | `scripts/offline-run.sh`, `scripts/limit-run.sh` | [Offline and memory](#offline-and-memory) |

Every Action mode downloads the prebuilt tools and corpus of one pinned release, checks each file against the
release's `SHA256SUMS` (and that file against your pin) before running, and writes a job summary with each failure,
what the ledger holds, what your reader did and the command that reproduces it.

## Expected-failure lists

A list names the entries your reader is known to get wrong, one per line. A run passes only when its failures are
exactly the list: a new failure fails it, and so does a listed failure that now passes (remove its line in the same
change as the fix). The format for replay is in [section 4](#4-the-expected-failure-list-for-replay); for SDKs in
[SDK CI, section 7](https://docs.xdrcheck.dev/guides/sdk-ci.md#7-an-expected-failure-list-and-the-all-read-check).

## Before you start

* No corpus release is published yet. Until one is, `uses: OWNER/REPO@v30.0.0` and the pin helper have nothing to
  download: build from a checkout and use `release-base` with a local `dist/` (`make release`, `make dist-bin`).
* `replay` and `conform` need a Linux runner.
* The kit's own workflows are described on [Architecture: CI](https://docs.xdrcheck.dev/architecture/ci.md); measured run times are on
  [Timings](https://docs.xdrcheck.dev/reference/ci-timings.md).

## GitHub Action

For indexer authors, SDK maintainers and Go teams who use GitHub Actions. One step in your workflow runs XDRCheck
against your code from the prebuilt tools and corpus of one pinned release, with nothing to build and nothing of
this repository to vendor:

| `mode` | For | Runs |
| - | - | - |
| `replay` | indexer authors | `xdrcheck replay`: the corpus's ledgers through your indexer via its adapter ([replay-harness.md](https://docs.xdrcheck.dev/reference/replay-harness.md), [adapter-protocol.md](https://docs.xdrcheck.dev/reference/adapter-protocol.md)) |
| `conform` | SDK maintainers | `xdrcheck conform`: the corpus through an SDK's conformance driver ([conformance-protocol.md](https://docs.xdrcheck.dev/reference/driver-protocol.md#conformance-rules)) |
| `lint` | Go indexer teams | `xdrlint` over your packages, with a SARIF file for code scanning ([lint/README.md](https://docs.xdrcheck.dev/guides/lint-go.md)) |

The action is `action.yml` at the repository root; `action/run.sh` does the work. Below, `OWNER/REPO` is this
repository on GitHub.

### 1. What it does

1. Downloads the release's `SHA256SUMS` and, when you give `sha256sums`, checks its sha256 against your pin.
2. Downloads the tools for the runner's platform (and, for `replay`, the corpus archive) from the GitHub release
   `v<corpus-version>`, checks each against `SHA256SUMS` before extracting it, and the extracted corpus against
   its own `SHA256SUMS` ([release.md §9](https://docs.xdrcheck.dev/guides/maintain-kit.md#9-release-assets-prebuilt-binaries-and-the-pin-helper)). A
   mismatch stops the step before anything runs.
3. Runs the mode, writes `SUMMARY.md` beside the tool's own reports and appends it to the job summary: the
   result, the expected-failure check, and the failures with what the ledger holds, what your reader did and the
   command that reproduces each one.
4. Uploads the report directory as an artifact (`xdrcheck-<mode>` by default), on failure too.

The step passes when the check passes. `replay` and `conform` need a Linux runner (`xdrcheck` is Linux-only);
`lint` runs on Linux and macOS.

### 2. Indexer authors: replay

Your adapter is a small program that drives your indexer for the harness; start from the template
[`go/adapters/minimal`](https://docs.xdrcheck.dev/guides/go-indexer) (or [`examples/adapter-ts`](https://docs.xdrcheck.dev/guides/any-language-indexer) for
other languages) and keep it in your repository. Then:

```yaml theme={null}
name: xdrcheck
on: [push, pull_request]
permissions:
  contents: read
jobs:
  replay:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: xdrcheck-adapter/go.mod
      - name: Build the adapter
        run: cd xdrcheck-adapter && go build -o "$RUNNER_TEMP/my-adapter" .
      - uses: OWNER/REPO@v30.0.0
        with:
          mode: replay
          corpus-version: 30.0.0
          sha256sums: 0000000000000000000000000000000000000000000000000000000000000000  # the release's SHA256SUMS sha256
          adapter: ${{ runner.temp }}/my-adapter
          target-version: ${{ github.sha }}
          expected-failures: .xdrcheck/replay.failures
          require-all-read: "true"
```

To see it work before writing anything, run the template itself: the release ships it, and the tools' directory
is on `PATH` during the step, so `adapter: minimal` replays the template indexer (and `adapter: demo` the
template with a planted bug, which fails with its repro commands in the job summary).

The default input is `sep54-dir`: ledgers as a SEP-54 layout in a plain directory, no Docker and no network.
`input: sep54-s3` or `rpc` serve them through an S3-compatible store or a mock `getLedgers` instead, if that is
how your indexer reads.

### 3. SDK maintainers: conform

```yaml theme={null}
jobs:
  conform:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
      - uses: OWNER/REPO@v30.0.0
        with:
          mode: conform
          corpus-version: 30.0.0
          columns: js@17.4.0
          expected-failures: conformance/js.failures
          require-all-read: "true"
```

`conform` runs from the action's own checkout, which holds the driver tree and the corpus of that release; it
fetches and builds the column's driver (`xdrcheck conform fetch`, `build`) and runs it. The runner needs the driver's
toolchain (Node for `js`, Go for `go`, Rust for `rust`, Python for `python`). `columns` names columns of the
driver sets ([driver-protocol.md](https://docs.xdrcheck.dev/reference/driver-protocol.md)): the pinned SDK releases. The expected-failure list is the
file `xdrcheck conform run --write-expected-failures` writes, with the rules of
[use-in-sdk-ci.md §7](https://docs.xdrcheck.dev/guides/sdk-ci.md#7-an-expected-failure-list-and-the-all-read-check);
without one, the corpus's declared divergences are the baseline (`xdrcheck conform check`).

A JavaScript SDK that wants to test its own build rather than a released version uses the npm package instead
([use-in-sdk-ci.md](https://docs.xdrcheck.dev/guides/sdk-ci.md)), downloaded with the pin helper (`fetch-release.sh --npm`,
[release.md §9](https://docs.xdrcheck.dev/guides/maintain-kit.md#9-release-assets-prebuilt-binaries-and-the-pin-helper)).

### 4. The expected-failure list for replay

An indexer keeps, in its own repository, the entry variants it is known to get wrong; the run then passes only
when its failures are exactly that list:

```text theme={null}
# <entry> <variant or -> [unread]
cap-0015/fee-bump-inner-failed pubnet
cap-0027/muxed-source-id-zero -
cap-0003/p10-upgrade-liabilities-50936-changes pubnet unread
```

| Line | Means |
| - | - |
| `<entry> <variant>` | this entry variant is expected to fail (any row of it with `failure: true` in `report.json`) |
| `<entry> -` | every variant of the entry |
| `… unread` | an entry variant your indexer never reads (every row not applicable, not reached, flaky or a harness fault) |

| Status | Fails the run | When |
| - | - | - |
| `NEW-FAILURE` | yes | a failing entry variant the list does not name: a regression |
| `UNEXPECTED-PASS` | yes | a listed entry variant that now passes: remove its line in the same change |
| `NOT-RUN` | yes | a listed entry the run has no row for: a misspelt or stale line (lines outside `entries` are ignored) |
| `NEW-UNREAD`, `MISSING` | with `require-all-read` | an entry variant never read, or an entry the harness plans with no row at all |
| `UNEXPECTED-READ` | with `require-all-read` | a line marked `unread` that is now read |

Write the first list from a run and review it before committing it:

```sh theme={null}
python3 action/replay_expect.py write REPORT_DIR/report.json --unread > .xdrcheck/replay.failures
python3 action/replay_expect.py check REPORT_DIR/report.json --expected .xdrcheck/replay.failures --require-all-read
```

`require-all-read` makes an adapter that declares an envelope too narrow, or a harness that silently plans
nothing, fail instead of passing on fewer entries.

### 5. Go teams: lint

```yaml theme={null}
jobs:
  xdrlint:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - id: xdrcheck
        uses: OWNER/REPO@v30.0.0
        with:
          mode: lint
          corpus-version: 30.0.0
          lint-paths: ./...
      - if: always() && steps.xdrcheck.outputs.sarif != ''
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.xdrcheck.outputs.sarif }}
```

`xdrlint` loads your packages with the Go toolchain, so the runner needs Go. Its diagnostics link to the rule
pages of the same release. `lint-args: -fail-on warning` fails on warnings too.

### 6. Inputs and outputs

| Input | Default | Meaning |
| - | - | - |
| `mode` | required | `replay`, `conform` or `lint` |
| `corpus-version` | the action's ref when it is a full version | the release, for example `30.0.0`, or a `-next` release such as `31.0.0-rc.1` ([release.md §8](https://docs.xdrcheck.dev/guides/maintain-kit.md#8-channels-stable-and-next)) |
| `sha256sums` | none | the sha256 of the release's `SHA256SUMS`: pins every downloaded byte to a value in your repository |
| `adapter` | | `replay`: your adapter's command line, run from `working-directory` |
| `target-version` | the commit | `replay`: the indexer version recorded in the report |
| `input` | `sep54-dir` | `replay`: `sep54-dir`, `sep54-s3` or `rpc` |
| `entries` | every entry | comma-separated entry ID globs (`*` crosses `/`) |
| `expected-failures` | none | your expected-failure list (section 4 for `replay`; `xdrcheck conform`'s format for `conform`) |
| `require-all-read` | `false` | fail on an entry variant never read unless the list names it `unread` |
| `columns` | | `conform`: column globs, for example `js@17.4.0` |
| `lint-paths` | `./...` | `lint`: package patterns |
| `lint-args` | none | `lint`: extra `xdrlint` flags |
| `working-directory` | `.` | where relative paths, the adapter and `xdrlint` run |
| `report-dir` | under the runner's temp directory | where the reports go |
| `artifact-name` | `xdrcheck-<mode>` | the uploaded artifact's name |
| `repository` | the action's own repository | `OWNER/REPO` whose release holds the assets (a fork's) |
| `release-base` | none | a URL prefix or local directory to read the release from instead (a mirror, or `dist/` of a local build) |

| Output | Meaning |
| - | - |
| `result` | `pass` or `fail` |
| `report-dir` | the directory with `SUMMARY.md`, `REPORT.md` and the machine-readable reports |
| `sarif` | `lint`: the SARIF file |

### 7. Pinning

`uses: OWNER/REPO@v30.0.0` fixes the action and, by default, the release. `uses: OWNER/REPO@v30` follows the
newest `30.x` action (the major tag moves with each release, [release.md §9](https://docs.xdrcheck.dev/guides/maintain-kit.md#9-release-assets-prebuilt-binaries-and-the-pin-helper));
then set `corpus-version`, so a new corpus reaches your CI only when you change the pin. For a supply-chain pin,
use the action at a full commit SHA and set `sha256sums`. Moving to the next protocol's corpus (`v31`) is always a
change of your pin, never a surprise.

### 8. Testing the action

`make action-selftest` runs `action.yml` step by step against the release in `dist/` (`make release`, then
`make dist-bin`) through `action/simulate.py`, a local stand-in for the runner that executes the composite steps
as written (the expressions they use, the runner's output and summary files, the artifact upload as a copy).
Every mode and failure path is a case: a passing and a failing replay, the expected-failure list and each status
that fails it, the all-read check, a corrupted asset and a wrong `SHA256SUMS` pin refused before anything runs,
lint's SARIF output, and, with `SELFTEST_CONFORM=1` after `make fetch-sdk`, a conformance run.

### 9. When the step fails

| Job summary or log says | Meaning | Do |
| - | - | - |
| a sha256 mismatch on `SHA256SUMS` or an asset | the download is not the release you pinned | check `sha256sums` against the release page; a mirror (`release-base`) must serve the same files |
| `NEW-FAILURE` | a regression, or new entries in a newer corpus | read the failure's repro command in the summary and run it locally |
| `UNEXPECTED-PASS` | a listed failure now passes | remove its line in the same change |
| `NOT-RUN`, `MISSING` | a stale line, or an entry with no row | fix or remove the line; check the adapter's envelope |
| every row `harness_fault` | the adapter did not start or broke the protocol | run `xdrcheck replay --adapter … --selftest` locally |
| `xdrlint` exit 2 | no package imports go-stellar-sdk's `xdr` package, or a package does not load | check `lint-paths` and `working-directory` |

The uploaded artifact (`xdrcheck-<mode>`) holds the full reports, including the adapter's stderr.

## Replay real ledgers in CI

For SDK maintainers who want real mainnet ledgers, not only corpus entries, in their CI. This recipe runs
`xdrcheck replay --set controls` against a branch of an SDK on every push and pull request: the same ledgers each
time, from a pinned dataset version, and a failed build when the branch shows a class of failure the released
version does not.

### What gets pinned

| Pin | How |
| - | - |
| the kit | a commit of this repository (`KIT_COMMIT`); `go build ./cmd/xdrcheck` from it |
| the dataset | a portable dataset archive made once with `xdrcheck data export` and published as a release asset; its sha256 is in the workflow (`DATASET_SHA256`) |
| the ledgers | they are the dataset's `controls` set; each ledger is fetched from the public lake and checked against its MD5, and the run manifest records each object's sha256 |
| the SDK | the branch under test is checked out by the job and given as a local path: `--version $GITHUB_WORKSPACE/sdk` |

Make the dataset archive once, where the full dataset is:

```text theme={null}
xdrcheck data export --set controls --out dataset-2026-11-17.1
tar -czf dataset-2026-11-17.1.tar.gz dataset-2026-11-17.1
sha256sum dataset-2026-11-17.1.tar.gz
```

### The job (GitHub Actions, in the SDK's repository)

This is the Go SDK; for JavaScript set up Node.js, check out `js-stellar-sdk`, build it (`npm ci && npm run build`)
and use `--target js`; for Python use `--target python` with a checkout of `py-stellar-base`.

```yaml theme={null}
name: xdrcheck replay
on: [push, pull_request]
permissions:
  contents: read
jobs:
  replay:
    runs-on: ubuntu-24.04
    env:
      KIT_COMMIT: 0000000000000000000000000000000000000000      # a commit of the kit
      DATASET_URL: https://github.com/OWNER/REPO/releases/download/dataset-2026-11-17.1/dataset-2026-11-17.1.tar.gz
      DATASET_SHA256: 0000000000000000000000000000000000000000000000000000000000000000
      XDRCHECK_DATASET: ${{ github.workspace }}/dataset-2026-11-17.1
      XDRCHECK_CACHE: ${{ github.workspace }}/.xdrcheck-cache
    steps:
      - uses: actions/checkout@v4
        with: { path: sdk }
      - uses: actions/checkout@v4
        with: { repository: OWNER/REPO, ref: ${{ env.KIT_COMMIT }}, path: kit }
      - uses: actions/setup-go@v5
        with: { go-version-file: kit/go/go.mod }
      - name: kit
        run: cd kit/go && go build -o "$GITHUB_WORKSPACE/xdrcheck" ./cmd/xdrcheck
      - name: dataset (pinned)
        run: |
          curl -sSfL "$DATASET_URL" -o dataset.tar.gz
          echo "$DATASET_SHA256  dataset.tar.gz" | sha256sum -c -
          tar -xzf dataset.tar.gz
          ./xdrcheck data status
      - uses: actions/cache@v4
        with:
          path: ${{ env.XDRCHECK_DATASET }}/lake
          key: lake-${{ env.DATASET_SHA256 }}
      - name: replay the controls through the released version (the baseline)
        run: ./xdrcheck replay --target go --version v0.9.0 --set controls --out run-base
      - name: replay the controls through this branch
        run: ./xdrcheck replay --target go --version "$GITHUB_WORKSPACE/sdk" --set controls --out run
      - name: check the run directories
        if: always()
        run: ./xdrcheck runs validate run-base run
      - name: no new class of failure
        run: ./xdrcheck runs compare --new-only run-base run
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: xdrcheck-run, path: run }
```

`runs compare --new-only` exits 1 when the branch has a cluster key the released version does not (`+` lines),
and 0 when the branch only removes some (`-` lines, a fix). A released SDK already shows candidates on real
ledgers, so failing on every candidate (`replay --fail-on candidate`) is only useful together with a dispositions
file (`--dispositions FILE`, kept in the SDK's repository) that names the accepted ones.

The exported dataset becomes a public release asset. Export only a set whose ledgers you are willing to publish
(`xdrcheck data export --set NAME`).

Any cluster in the job's run directory can be packed into a bundle (`xdrcheck repro pack run --cluster KEY`,
[repro.md](https://docs.xdrcheck.dev/reference/replay-target.md#repro)) that reproduces it on a laptop with one command.

Limits: the job needs the network to fetch ledgers from the public lake on a cold cache (the `actions/cache` step
keeps them afterwards). `--target` takes `go`, `js`, `python`, `rust` and the service rigs
([replay.md](https://docs.xdrcheck.dev/reference/replay-target.md)); the comparison is by cluster key, so a branch that changes a failure's details without
changing its class is not reported.

## Offline and memory

For anyone running the kit's checks in CI or on a workstation who needs to know that a run used no network and
stayed within a memory bound. Two wrappers enforce this. Both were exercised on Debian 13, kernel 6.12, cgroup v2.
Add `OFFLINE=1` to a `make` target to run it under the network wrapper.

### No network: `scripts/offline-run.sh`

Runs a command in a private network namespace with only a loopback interface
(`unshare --user --map-root-user --net`). Local servers (stellar-core's HTTP port, the mock RPC, the object store)
keep working on loopback; nothing can reach the internet. Verified: an HTTPS request fails to connect, and a
socket binds on 127.0.0.1.

A container's published ports are not on that loopback, so the wrapper sets `XDRCHECK_OBJSTORE=binary` unless the
caller set it: the replay harness's object store then runs as the pinned SeaweedFS image's own `weed` executable
(same digest) inside the namespace.

Fallback where unprivileged user namespaces are disabled: `XDRCHECK_OFFLINE_FALLBACK=docker` with a pinned toolbox
image runs the command in a container with `--network none`.

Dependencies are fetched beforehand by `make fetch`, the only networked step.

### Memory: `scripts/limit-run.sh`

Runs a command under a memory limit.

| Mechanism | When | Behaviour on overflow | Verified |
| - | - | - | - |
| cgroup v2 `MemoryMax` via `systemd-run --user --scope` | default when available | the kernel kills the group (exit 137) | a 200 MiB allocation under a 64 MiB limit was killed; an 8 MiB one succeeded |
| `prlimit --as` (address space) | `XDRCHECK_LIMIT_MECHANISM=rlimit`, or no user systemd | allocation fails inside the process (`MemoryError`, `ENOMEM`) | a 200 MiB allocation under 64 MiB raised `MemoryError` |

The two behave differently on purpose: the memory-bound test runs under the cgroup limit (what a container
runtime does), and negative vectors with huge length prefixes are also run under the address-space limit, where
an implementation that pre-allocates fails visibly instead of being killed. Reports record which mechanism was
used.

Limits: the wrappers are verified on the machine above, not yet on hosted CI runners. The network namespace
needs unprivileged user namespaces; where they are disabled, use the Docker fallback.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.