Skip to main content
skill CX Codex

dart-ci — Claude Code skill: debugging DART CI on GitHub Actions

Walks an agent through a failed DART CI run: gh calls for logs, a table of platform-specific breakages, and a local repro loop.

BSD-2-Clause 1 installs ★ 1,232 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dartsim/dart --skill dart-ci -a claude-code
Open on GitHub

What dart-ci does

The skill fires when a PR check goes red or something looks off in GitHub Actions. It hands the agent a set of gh calls: list runs for a branch, pull the failing job log with gh run view <RUN_ID> --job <JOB_ID> --log-failed, read status and URL as JSON. Reruns are gated: the skill says to do them only once a maintainer or the user says yes.

A table maps common breakages to fixes. Lint failures go through pixi run lint. A Codecov patch complaint means writing tests for the lines nobody covered. On FreeBSD, RTTI trouble is fixed by swapping dynamic_cast for static_cast with a type enum; a SEGFAULT on macOS ARM64 by moving from alloca() and VLAs to std::vector<T>. Filament has its own lane: configure with -DDART_ENABLE_GUI_SMOKE_TESTS=ON, then pixi run test-gui, and native-window failures on headless Linux go under xvfb-run. That smoke option is off by default and wants a graphics device.

There is also a workflow map covering the Ubuntu, macOS, Windows, FreeBSD, SIMD, toolchain and Gazebo pipelines with their platforms. FreeBSD, toolchain, CodeQL, wheels and a few other legs run only in nightly.yml; their failures land as nightly-failure issues rather than PR checks. A red nightly will not show up in the PR list, so looking there wastes time. On cache problems the skill is blunt: read the restore and save steps and the job timestamps instead of trusting any estimate of how long a run should take.

What it helps with

  • read the failing job log to see which step broke the PR
  • reproduce a gz-physics failure locally with pixi run -e gazebo test-gz
  • clear a macOS ARM64 SEGFAULT by dropping alloca() for std::vector<T>
  • work out why a failure never appeared among PR checks
  • run the Filament GUI smoke tests and locate the window problem

Example prompts for the agent

  • Check why ci_macos.yml failed on PR <PR_NUMBER> and show me the failing job log.
  • Reproduce the gz-physics failure in the gazebo environment and tell me what to change.
  • Get the status of run <RUN_ID>; do not rerun anything until I approve.

How to install dart-ci

1Skills CLI (Vercel)

npx skills add dartsim/dart --skill dart-ci -a claude-code

2Manually: put the files in place

~/.claude/skills/dart-ci/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dart-ci/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dart-ci

How do I install dart-ci in Claude Code?

Run npx skills add dartsim/dart --skill dart-ci -a claude-code. The skill lands at ~/.claude/skills/dart-ci/SKILL.md.

What does dart-ci do?

It gives the agent gh commands, a failure-mode table and repro steps for broken DART runs in GitHub Actions.

Where do nightly failures show up?

Several legs run only in nightly.yml and report as nightly-failure issues instead of PR checks.

Source text

SKILL.md · BSD-2-Clause
---
name: dart-ci
description: "DART CI: GitHub Actions, cache debugging, and platform-specific failures"
---

# DART CI/CD Troubleshooting

Load this skill when debugging CI failures or working with GitHub Actions.

When the failing claim depends on model/scene structure, physics behavior, or
Filament output, also load `dart-verify-sim` and reproduce it with a text oracle plus
assessed visual evidence. Document a visual exception when graphics support is
unavailable or not applicable in the failing environment.

## Quick Commands

```bash
# Monitor PR checks
gh pr checks <PR_NUMBER>
gh pr view <PR_NUMBER> --json headRefOid,mergeStateStatus,statusCheckRollup

# View run details
gh run list --branch <BRANCH> -e pull_request -L 20
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 only after explicit maintainer/user approval
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`; push only after approval                |
| 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`              |
| CI Filament fails    | Configure with `pixi run config -- -DDART_ENABLE_GUI_SMOKE_TESTS=ON`, then run `pixi run test-gui`; native-window failures with `pixi run ctest --test-dir build/<env>/cpp/Release -L filament-native` (`pixi run ctest --test-dir build/<env>/cpp -C Release -L filament-native` on Windows; under `xvfb-run` on headless Linux); consumer failures with `pixi run python scripts/test_gui_install.py` on that build directory |

## Workflow Architecture

The CI workflows that a failing PR check belongs to (full workflow index:
`docs/onboarding/ci-cd.md` § "Workflow Index"):

| Workflow            | Purpose                                | Platforms  |
| ------------------- | -------------------------------------- | ---------- |
| `ci_ubuntu.yml`     | AI checks, lint, build, test, coverage | Ubuntu     |
| `ci_macos.yml`      | Lint, build, test                      | macOS      |
| `ci_windows.yml`    | Lint, build, test                      | Windows    |
| `ci_filament.yml`   | Filament GUI functional lane (`<runner>-Filament-functional`; not yet required) | Ubuntu, macOS; Windows nightly |
| `ci_freebsd.yml`    | Build + test (VM)                      | FreeBSD    |
| `ci_simd.yml`       | SIMD x86 instruction-level matrix      | Ubuntu x86_64 |
| `ci_toolchain.yml`  | Alternate toolchain build + test       | Ubuntu     |
| `ci_gz_physics.yml` | Gazebo integration                     | Ubuntu     |
| `api_doc.yml`       | Doxygen API docs build                 | Ubuntu     |

FreeBSD, toolchain, CodeQL, wheels, Linux ASan/coverage/Eigen alignment, macOS
install, the Windows VS 2022 leg and build-requirement checks, and the Filament
Windows leg run only in `nightly.yml`; their failures arrive as
`nightly-failure` issues, not PR checks.

Default test gates exclude device-dependent CTests labeled `gui-device` and
Python rendering tests; device-free GUI tests still run. `pixi run test-gui`
selects all `gui` CTests except `filament-native`. The capture smoke option
`DART_ENABLE_GUI_SMOKE_TESTS` defaults to `OFF`, needs a graphics device, and
replaces `DART_ENABLE_GUI_OSG_SMOKE_TESTS`; `CI Filament` enables it.

## Downstream Compatibility Policy

Package, exported-target, collision, constraint, and dependency changes can
affect Gazebo/gz-physics even when local unit tests pass. Reproduce those
failures with the Gazebo Pixi environment when practical:
`pixi run -e gazebo test-gz`.

## Fast Iteration Loop

1. Identify failing step from job logs
2. Reproduce locally with same build toggles
3. Fix the smallest failing test
4. Push only after explicit maintainer/user approval, then monitor:
   `gh run view <RUN_ID> --json status,conclusion,url`

## Caching And Duration

Treat the current run and job logs as authoritative. Inspect cache restore/save
steps and job timestamps before changing a key; do not rely on fixed duration
or cache-speed estimates in this skill.

© dartsim · BSD-2-Clause · dartsim/dart

Similar skills

All skills for DevOps and infrastructure →

From the same set2

Project sponsors

Companies that keep this analytics open