Menu
Run Erigon CI checks locally and/or trigger them remotely on a branch via GitHub Actions workflow_dispatch. Use this when you need to verify a branch passes all CI before or after pushing — especially for branches like bal-devnet-2 that don't auto-trigger on push/PR events.
Use the 'erigon seg step-rebase' command to change the step size of an existing datadir. Use when the user wants to rebase segments or modify step sizes.
Run the full Erigon test suite locally using GOGC=80 make test-all. Use this before marking a PR ready for review. Equivalent to the "All tests" CI workflow.
Run Erigon tests with Go race detector to find data races and concurrency bugs. Use this for concurrency-sensitive changes (parallel executor, p2p, txpool). Takes 30-60 minutes.
Implement a new EIP for a hardfork under development in Erigon. Use when the user asks to implement, port, or wire up an EIP — covers spec lookup, dep analysis, prior-work check, implementation, lint, tests, and a wrap-up saved to `agentspecs/`.
Run benchmarkoor performance benchmarks against a locally-built Erigon binary and produce per-test MGas/s comparison tables. Covers image build, dataset reset, run invocation, result parsing, and before/after comparisons.
Run an ephemeral Erigon instance with a temporary datadir. Use this whenever the user wants to spin up a temporary, throwaway, or sandboxed Erigon node for quick testing, launch a second Erigon instance alongside an existing one, clone a datadir into a temp copy for safe experimentation, or find and clean up leftover ephemeral datadirs and processes from previous sessions. Handles port conflict detection and automatic port offsetting. Trigger on any mention of temporary/throwaway/ephemeral/disposable Erigon instances, running erigon briefly for testing or debugging, starting a second/additional erigon node, or cleaning up old temp erigon data.
| name | erigon-ci |
| description | Run Erigon CI checks locally and/or trigger them remotely on a branch via GitHub Actions workflow_dispatch. Use this when you need to verify a branch passes all CI before or after pushing — especially for branches like bal-devnet-2 that don't auto-trigger on push/PR events. |
Orchestrates CI verification: run test groups locally and/or dispatch GitHub Actions on any branch.
Each test group has its own dedicated skill for drill-down on failures. Use those when a specific group fails and you need to re-run individual tests.
| Group | Skill | Command | Speed | Use When |
|---|---|---|---|---|
| lint | (inline) | make lint | ~1 min | Before every push |
| unit | erigon-test-unit | make test-short | ~5 min | Pre-push gate |
| all | erigon-test-all | GOGC=80 make test-all | ~30 min | Before PR review |
| race | erigon-test-race | make test-all-race | ~60 min | Concurrency changes |
| eest-spec | (inline) | make eest-spec-<suite>-<fixtures>[-{sequential,parallel}] | varies | EEST state/blockchain/engine-x changes (most shards split into -sequential / -parallel pairs that pin ERIGON_EXEC3_PARALLEL; see tools/eest-spec-shards.yml) |
| caplin spec | (inline) | cd cl/spectest && make tests && make mainnet | ~15 min | CL/consensus changes |
| hive | erigon-test-hive | make test-hive | ~20 min | EL/CL interop changes |
| rpc | erigon-test-rpc | (requires synced DB) | ~10 min | RPC API changes |
| assertoor | (remote only) | dispatch only | — | Kurtosis network test |
make test-all no longer covers the EEST spec tests or the cl/spectest consensus spec test — run those via their dedicated targets above when relevant.
Pitfall: prefer make eest-spec-<shard> over bash tools/run-eest-spec-test.sh <shard>. The make target lists evm / evm.race as a prereq so stale binaries get rebuilt; the script invoked directly does not, and a stale binary against current fixtures will inflate failures or hide regressions.
make lint
make lint && make test-short
make lint && make erigon integration && GOGC=80 make test-all
make lint && make test-all-race
Use gh workflow run to trigger workflows on a branch. Required for branches not targeting main (e.g. bal-devnet-2).
BRANCH=$(git branch --show-current) # or set explicitly: BRANCH="bal-devnet-2"
for wf in \
"Unit tests" \
"All tests" \
"EEST spec tests" \
"Lint" \
"Test Hive" \
"Kurtosis Assertoor GitHub Action" \
"QA - RPC Integration Tests" \
"QA - RPC Integration Tests Remote" \
"QA - RPC Integration Tests (Gnosis)" \
"Windows downloader tests"; do
echo "Dispatching: $wf"
gh workflow run "$wf" --ref $BRANCH
done
| Workflow name (GitHub) | dispatch? | Local skill | File |
|---|---|---|---|
| Unit tests | yes | erigon-test-unit | ci.yml |
| All tests | yes | erigon-test-all | test-all-erigon.yml |
| EEST spec tests | yes | (make eest-spec-…) | test-eest-spec.yml |
| Lint | yes | (make lint) | lint.yml |
| Test Hive | yes | erigon-test-hive | test-hive.yml |
| Kurtosis Assertoor GitHub Action | yes | (remote only) | test-kurtosis-assertoor.yml |
| QA - RPC Integration Tests | yes | erigon-test-rpc | qa-rpc-integration-tests.yml |
| QA - RPC Integration Tests Remote | yes | erigon-test-rpc | qa-rpc-integration-tests-remote.yml |
| QA - RPC Integration Tests (Gnosis) | yes | erigon-test-rpc | qa-rpc-integration-tests-gnosis.yml |
| Windows downloader tests | yes | (remote) | test-win-downloader.yml |
| Consensus spec | no | (PR-only) | test-integration-caplin.yml |
Note: Consensus spec has no workflow_dispatch — only fires on pull_request events targeting main/release.
BRANCH=$(git branch --show-current)
gh run list --branch $BRANCH --limit 15
Check for failures:
gh run list --branch $BRANCH --limit 20 | grep -E "failure|cancelled"
Watch a specific run:
gh run watch <run-id>
When preparing a devnet/feature branch for review:
Local gate — fast feedback before pushing:
make lint && make erigon integration && make test-short
Push branch:
git push origin <branch>
Dispatch all remote workflows (use the loop from Part 2).
Monitor until all pass:
gh run list --branch $(git branch --show-current) --limit 15
Race check (for concurrency-heavy changes):
make test-all-race