Guides

Run locally

Rehearse a check on your own machine, reproduce a refusal exactly, and what to do when land is unreachable.

What runs where

Merging and checking happen on land's machines, because that is what lets land sign the result. A commit is proven only by land merge. On your own machine you can rehearse a check before you connect a repository, reproduce any refusal exactly, and verify commits offline.

Rehearse a check

The quickest way to get .land/setup.sh right is to run it the way land does, in a plain Debian container with the network on, then run the tests in it with the network off.

# 1. build the environment: run your setup script once, with the network on
docker run --name land-env -v "$PWD":/repo -w /repo debian sh .land/setup.sh
docker commit land-env land-env && docker rm land-env

# 2. run the tests the way land does: offline, from the repository root
docker run --rm --network none -v "$PWD":/repo -w /repo land-env python3 -m pytest -q

A plain Debian container is close to land's machine but not identical, so a test that passes here can still fail on land. land add --dry-run shows exactly what would be uploaded, and the first land add runs the real check.

Reproduce a refusal

Every refused branch comes with repro, a commit and a command. The commit is the exact merged code that failed, and land has already downloaded it into your repository.

# from a refused verdict: land already downloaded repro.commit into your repository
git checkout 071366837c
python -m pytest tests/test_ledger.py::test_reverse

Verify a commit

land verify runs entirely on your machine. It checks land's signature for a commit with no network after the keys are saved. See Checking a commit.

When land is unreachable

Merge and test locally instead, and treat the result as unverified. Don't push it to a protected branch without a person's OK. Once land is back, run land merge again to get a signed result.

git fetch origin main
git switch -c try/merge origin/main
git merge --no-edit agent/api agent/ledger
python -m pytest -q   # unverified by land