Overview
StackProbe uses exit codes to communicate audit results, making it easy to integrate into CI/CD pipelines and automated workflows.
Exit Code Behavior
Exit Code 0 (Success)
StackProbe exits with code 0 when:
- All checks pass
- Checks pass with warnings only
- All checks are skipped
Example scenarios:
# All checks pass
stackprobe audit
# Exit code: 0
# Some checks warn, but none fail
stackprobe audit
# Exit code: 0 (warnings don't fail the build)
Exit Code 1 (Failure)
StackProbe exits with code 1 when:
- One or more checks fail
- A check crashes unexpectedly
Implementation reference: runner.ts:84
// Exit with code 1 if any check failed — useful for CI
const hasFail = results.some((r) => r.status === "fail");
if (hasFail) process.exit(1);
# Dependency check fails
stackprobe audit
# Exit code: 1
# Specific check fails
stackprobe audit --only engine
# Exit code: 1 (if engine check fails)
Check Status Levels
Each check returns one of four status levels:
| Status | Impact on Exit Code | Description |
|---|
pass | Exit 0 | Check completed successfully with no issues |
warn | Exit 0 | Check found potential issues but not critical |
fail | Exit 1 | Check found critical issues that must be fixed |
skip | Exit 0 | Check was skipped (via ignore config) |
CI/CD Integration
GitHub Actions
- name: Run StackProbe audit
run: npx stackprobe audit
# Workflow will fail if exit code is 1
GitLab CI
audit:
script:
- npx stackprobe audit
# Job fails if exit code is non-zero
CircleCI
- run:
name: StackProbe audit
command: npx stackprobe audit
Using JSON Output in CI
Capture and parse JSON output for custom behavior:
# Capture JSON output
stackprobe audit --json > audit-results.json
# Check exit code
if [ $? -ne 0 ]; then
echo "Audit failed"
# Parse results for custom handling
cat audit-results.json | jq '.results[] | select(.status == "fail")'
fi
Error Handling
If a check crashes unexpectedly, StackProbe handles it gracefully:
- The crashed check is reported as a
fail status
- An error message is added to the results
- Other checks continue to run
- The audit exits with code
1
Implementation reference: runner.ts:58-71
try {
const result = await checkFn();
result.duration = Date.now() - checkStart;
results.push(result);
} catch (err) {
// If a check crashes, report it as a fail — don't crash the whole audit
results.push({
checkName: name,
status: "fail",
messages: [
{
level: "error",
text: `Check crashed unexpectedly: ${(err as Error).message}`,
},
],
duration: Date.now() - checkStart,
});
}
Best Practices
Warnings don’t fail builds — StackProbe only exits with code 1 for actual failures. This allows you to catch warnings without blocking deployments.
stackprobe audit || exit 1
# Fast checks first
- npx stackprobe audit --only deps,env
# Slower checks later
- npx stackprobe audit --only circular