DART CI/CD Troubleshooting
Load this skill when debugging CI failures or working with GitHub Actions.
Quick Commands
Monitor PR checks
gh pr checks <PR_NUMBER> gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast
View run details
gh run list --branch <BRANCH> -e pull_request -L 20 gh run watch <RUN_ID> --interval 30 gh run view <RUN_ID> --json status,conclusion,url
Debug failures
gh run view <RUN_ID> --job <JOB_ID> --log-failed gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'
Rerun failed jobs
gh run rerun <RUN_ID> --failed gh run rerun <RUN_ID> --job <DATABASE_ID>
Full Documentation
For complete CI/CD guide: docs/onboarding/ci-cd.md
Common Failure Modes
Failure Type Solution
Formatting fails pixi run lint then push
Codecov patch fails Add tests for uncovered lines
FreeBSD RTTI fails Use type enums + static_cast instead of dynamic_cast
macOS ARM64 SEGFAULT Replace alloca() /VLAs with std::vector<T>
RTD build fails Use defensive .get(key, default) patterns
gz-physics fails Reproduce with pixi run -e gazebo test-gz
Workflow Architecture
Workflow Purpose Platforms
ci_lint.yml
Formatting Ubuntu
ci_ubuntu.yml
Build + test + coverage Ubuntu
ci_macos.yml
Build + test macOS
ci_windows.yml
Build + test Windows
ci_freebsd.yml
Build + test (VM) FreeBSD
ci_gz_physics.yml
Gazebo integration Ubuntu
Fast Iteration Loop
-
Identify failing step from job logs
-
Reproduce locally with same build toggles
-
Fix the smallest failing test
-
Push and monitor: gh run watch <RUN_ID>
Caching
-
sccache/ccache reduces build time 50-70%
-
Check cache hit rates in workflow logs
-
Force cache bust by changing cache key if needed
Expected CI Times
Platform Cached Uncached
Ubuntu 20-30 min 45-60 min
macOS 15-25 min 30-45 min
Windows 15-20 min 25-35 min