oss-debug-ci
Debug CI failures in unfamiliar repo pipelines. Reads CI configs, fetches failure logs, classifies the failure type, and guides the user through diagnosing and fixing the issue. Use when CI fails on your PR in an OSS repo, when you don't understand a CI error, or when debugging GitHub Actions/CircleCI/other CI systems. Not for setting up CI from scratch — this is for debugging existing pipelines.
chiruu12 · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add chiruu12/OSS-Skills --skill oss-debug-ci技能说明
name: oss-debug-ci description: | Debug CI failures in unfamiliar repo pipelines. Reads CI configs, fetches failure logs, classifies the failure type, and guides the user through diagnosing and fixing the issue. Use when CI fails on your PR in an OSS repo, when you don't understand a CI error, or when debugging GitHub Actions/CircleCI/other CI systems. Not for setting up CI from scratch — this is for debugging existing pipelines.
Debug CI
CI failed on someone else's repo and the error makes no sense. This skill teaches you to read CI pipelines, classify failures, and fix them — instead of pushing blind patches and hoping.
Purpose
CI failures in unfamiliar repos are disorienting. The error might come from a linter you've never configured, a test runner with custom settings, or a platform-specific incompatibility. Most contributors respond by pushing random fixes until green. This skill teaches you to read the pipeline, understand what failed and why, determine if it's your fault, and fix it systematically.
When to Use
- CI fails on your PR and you don't understand the error
- CI failure is in a tool/system you haven't used before
- You suspect the failure is pre-existing (flaky test, broken main)
- You need to reproduce a CI failure locally
- NOT when setting up CI for a new project — that's infrastructure work
- NOT when CI passes but the code is wrong — that's
oss-contribute
Prerequisites
- A PR submitted to an OSS repo (from
oss-submit-pr) ghCLI authenticated- Access to the CI logs (public repo or you have permissions)
Process
1. Identify the CI system and read the config
Before looking at logs, understand the pipeline structure.
# Find CI configuration files
ls -la .github/workflows/ 2>/dev/null
ls -la .circleci/ 2>/dev/null
ls -la .travis.yml Jenkinsfile .gitlab-ci.yml .buildkite/ azure-pipelines.yml 2>/dev/null
# Read the relevant workflow
cat .github/workflows/ci.yml # or whatever the CI config is
Map the pipeline:
- What jobs exist? (build, test, lint, typecheck, etc.)
- What order do they run in? (parallel or sequential?)
- What OS/container do they run on? (ubuntu, macos, windows, custom image?)
- What language/tool versions are pinned? (node 20, python 3.12, go 1.22?)
- What caching is used? (dependency caching, build caching?)
2. Fetch the failure logs
Your PR's CI runs on the upstream repo, not on your fork. Name the repo on every
command. Without -R, gh guesses from your remotes, and in a fork clone it can
guess your fork, which has no runs for this PR.
# Start here. This maps each check to the run and job that produced it.
gh pr checks {pr-number} -R {owner}/{repo}
# Or list runs by head branch. Your fork's branch name is the head branch upstream.
gh run list -R {owner}/{repo} --branch {your-branch} --limit 5
# View the failed run
gh run view {run-id} -R {owner}/{repo}
# Get the specific failure logs
gh run view {run-id} -R {owner}/{repo} --log-failed
# If you need the full log for a specific job
gh run view {run-id} -R {owner}/{repo} --log --job {job-id}
Isolate the actual error from surrounding noise. CI logs are verbose — most of the output is setup and teardown. The failure is usually in the last 20-50 lines of a failed step.
3. Classify the failure
Determine what kind of failure you're dealing with. This determines your fix strategy.
| Failure Type | Signals | Fix Strategy |
|---|---|---|
| Build error | Compilation failed, import not found, type error | Your code has a syntax or type issue. Fix locally. |
| Test failure | Assertion failed, expected X got Y | Your changes broke a test. Read the test to understand what it expects. |
| Lint/format failure | Style violation, unused import, formatting diff | Run the repo's formatter/linter locally. Often auto-fixable. |
| Dependency resolution | Package not found, version conflict, lockfile mismatch | You changed deps or the lockfile is stale. Regenerate it. |
| Environment mismatch | Works locally, fails in CI | Different OS, different tool version, missing env var. |
| Flaky test | Test passes sometimes, fails sometimes. Same code. | Not your fault. Check if this test fails on main too. |
| Pre-existing failure | Main branch has the same failure | Not your fault. Comment on PR noting pre-existing failure. |
| Timeout | Job exceeded time limit | Your changes might be slow, or CI is under load. Check if it's reproducible. |
| Permission/secret issue | Auth failed, secret not found | Fork PRs can't access repo secrets. Check if the job needs secrets. |
4. Determine if the failure is yours
This is the critical question. Don't fix what isn't broken.
# Check if the same job fails on main
gh run list -R {owner}/{repo} --branch main --limit 5 --workflow {workflow-name}
gh run view {latest-main-run-id} -R {owner}/{repo} --log-failed
# Check if this test is known to be flaky
gh issue list -R {owner}/{repo} --search "flaky {test-name}" --state open
gh issue list -R {owner}/{repo} --label "flaky" --state open
# Try rebasing onto latest main — maybe the failure was already fixed
git fetch origin main
git rebase origin/main
If the failure exists on main: it's not your problem. Comment on your PR:
CI failure in `{job-name}` appears to be pre-existing — the same test fails on main ([run link]). Happy to help fix separately if useful.
5. Reproduce locally
If the failure IS from your changes, reproduce it before fixing blindly.
# Run the exact command CI runs (read it from the CI config)
# Don't guess — copy the exact command from the workflow file
# Common examples:
npm run test # not just "npm test" if the script is different
pytest -x # might need specific flags
make lint # might include multiple linters
cargo clippy -- -D warnings # might treat warnings as errors
If it pa
阅读完整来源 ↗