CI Troubleshoot

CI Troubleshoot

Diagnose CI failures for pi-agent-dashboard. The repo has 11 workflow files: 9 entry workflows and 2 reusable workflows.

flowchart LR
  ci[ci.yml] --> checks[guards + lint + build<br/>+ affected tests]
  nightlyTests[nightly-tests.yml] --> full[full suite + nightly-tests issue]
  deploy[deploy-site.yml] --> pages[GitHub Pages]
  native[ci-e2e-electron.yml] --> nativeTests[native Electron E2E]
  ciSmoke[ci-smoke.yml] --> smoke[_smoke.yml]
  publish[publish.yml] --> smoke
  ciElectron[ci-electron.yml] --> electron[_electron-build.yml]
  nightly[nightly.yml] --> electron
  publish --> electron
  publish --> release[GitHub Release]
  release --> sync[sync-release-version.yml]

Full per-workflow detail: references/workflow-taxonomy.md.

First moves — always run these

pnpm exec tsx .pi/skills/ci-troubleshoot/scripts/list-recent-runs.ts                  # last 10 runs across all workflows
pnpm exec tsx .pi/skills/ci-troubleshoot/scripts/list-recent-runs.ts --failed         # only failed
pnpm exec tsx .pi/skills/ci-troubleshoot/scripts/show-failed-run.ts <run-id>          # failed steps + log tails
pnpm exec tsx .pi/skills/ci-troubleshoot/scripts/show-failed-run.ts                   # most recent failed run

These wrap gh run list, gh run view --log-failed, and similar. You need gh auth status to be authenticated.

ci.yml job taxonomy — affected-only tests

ci.yml runs parallel jobs (change: speed-up-ci-affected-tests):

What did this run skip? Open the select job summary, or:

gh run download <run-id> -n test-selection -D /tmp/sel
jq '{mode, reason, counts, slowTierDeselected, unmapped}' /tmp/sel/selection.json
jq -r '.selected | to_entries[] | "\(.value)\t\(.key)"' /tmp/sel/selection.json | sort | head   # file → layer
jq '.shards | map(length)' /tmp/sel/selection.json

Mode full has a reason: a global input (lockfile, root package.json, any vitest/tsconfig, setupFiles, the selector or its data), an unmapped file outside packages/, a ci:full label, workflow_dispatch, or a selector error (all-zero/non-ancestor/missing base).

Force a full run. ci:full label on the PR → takes effect on the NEXT push (there is no labeled trigger — on purpose). Immediate: gh workflow run ci.yml --ref <branch> (dispatch is always full).

Slow tier. scripts/test-selection/slow-tier.json (only the 504 s mutation harness) is deselected in affected mode unless the file itself changed; it runs nightly, in full mode, and under ci:full. Listed under "Slow-tier deselections" in the summary.

A test is green on PRs but red nightly. Not automatically a selection miss — flakes and environment changes do this too. The nightly-tests issue names the bisect range (A..B, since the last green SCHEDULED run). Bisect in that range to the breaking commit, then open that commit's PR run test-selection artifact: if the failing file WAS selected (and executed), debug the test itself; only if it was NOT selected did selection miss it — close the gap with a scripts/test-selection/triggers.json entry or a layer fix, never just a re-run.

nightly-tests issue triage. One open issue, label nightly-tests, updated each red scheduled night, closed on the first green one. "no report" = a job was cancelled or died (infra), not a pass. "no new commits" = flake or environment. Refreshed shard timings: artifact test-timings → copy to scripts/test-selection/timings.json by hand.

Unit-test failure → read the vitest-report-* artifact FIRST, not the log. Each vitest job uploads its own report on every run (if: always(), 14-day retention): vitest-report-unit-<n>, vitest-report-real-process, vitest-report-ci-scenarios.

gh run download <run-id> -p 'vitest-report-*' -D /tmp/vr
# failures
jq -r '.testResults[].assertionResults[] | select(.status=="failed") | .fullName' /tmp/vr/*/vitest*.json
# RETRIED PASSES — passed, but a failed attempt's error is still retained
jq -r '.testResults[].assertionResults[] | select(.status=="passed" and (.failureMessages|length)>0) | .fullName' /tmp/vr/*/vitest*.json

There is no retryCount field. Vitest 4.1.11's JSON reporter emits only {ancestorTitles, fullName, status, title, duration, failureMessages, meta, tags}; retryCount lives on the runner API, not the report. The retried-pass signature is therefore status == "passed" with a non-empty failureMessages. Verified empirically against a fail-once fixture; re-verify after a vitest major upgrade — if the second query returns nothing on a run you know flaked, the reporter shape moved.

Retry semantics: ONLY the server-real-process project retries, ONLY under CI, ONLY once (retry: process.env.CI ? 1 : 0). A green job whose report matches the retried-pass query did NOT pass cleanly — that test flaked. A test failing twice still reds the job. Locally retry is 0. The default reporter prints (retry x1) only for tests it lists; a retried PASS is invisible there, which is why the artifact is the first move. Locally npm test = test:parallel then test:real-process; in CI the real-process phase is its own real-process job running vitest run --config packages/server/vitest.real-process.config.ts.

Scripts are TypeScript and cross-platform. All invocations use pnpm exec tsx, which resolves the declared local dependency and fails if dependencies are absent. gh CLI is cross-platform.

Triage decision tree

flowchart TD
  red{Run is red?} --> workflow{Which workflow?}
  workflow --> ci[ci.yml]
  workflow --> publish[publish.yml]
  workflow --> electron[ci-electron.yml]
  workflow --> other[Other workflow]
  ci --> common[Tests, lint, build<br/>references/common-failures.md]
  other --> taxonomy[references/workflow-taxonomy.md]
  publish --> releaseJob{Which release job?}
  releaseJob --> tag[tag-and-push]
  releaseJob --> npmOrder[publish: npm ordering]
  releaseJob --> matrix[electron: matrix leg]
  releaseJob --> assets[github-release: asset collision]
  electron --> smoke[On-demand Electron smoke<br/>never publish]

Release pipeline — publish.yml

The release flow uses a gated 7-job graph:

flowchart LR
  resolve[resolve] --> checks[ci-checks]
  resolve --> smoke[smoke via _smoke.yml]
  checks --> tag[tag-and-push]
  smoke --> tag
  tag --> publish[publish packages]
  publish --> electron[electron via _electron-build.yml]
  electron --> release[github-release]

Tag-push runs skip tag-and-push; publish.if accepts that skip while still requiring checks and smoke. Do not remove needs: [resolve, publish] from electron. The bundled server installs the just-published packages. Locked by packages/shared/src/__tests__/publish-workflow-contract.test.ts.

Full walkthrough with per-job failure modes: references/release-pipeline.md.