fixing-streamlit-ci

修复 CI 失败

使用 gh CLI 和 git 命令，诊断并修复当前分支/PR 上失败的 GitHub Actions CI 任务。

何时使用

• PR 上的 CI 检查已失败
• 你需要了解某个工作流为何失败
• 你希望应用修复并在本地验证

工作流

复制此清单以跟踪进度：

- [ ] Verify authentication
- [ ] Gather context & find failed jobs
- [ ] Download & analyze logs
- [ ] Present diagnosis to user
- [ ] Apply fix & verify locally
- [ ] Push & recheck CI

1. 验证身份认证

gh auth status

如果身份认证失败，提示用户使用适当的 scope 运行 gh auth login。

2. 收集 PR 上下文

# Get PR for current branch
gh pr view --json number,title,url,headRefName

# Get PR description and metadata
gh pr view --json title,body,labels,author

# List changed files
gh pr diff --name-only

# All changes
gh pr diff

3. 检查 CI 状态

# List all checks (shows pass/fail status)
gh pr checks

# Get detailed check info
gh pr checks --json name,state,conclusion,detailsUrl,startedAt,completedAt

# List only failed runs
gh run list --branch $(git branch --show-current) --status failure --limit 10

# Check if CI is still running
gh run list --branch $(git branch --show-current) --status in_progress

4. 查找失败的任务

# View run details (get RUN_ID from previous step)
gh run view {RUN_ID}

# List failed jobs with IDs
gh run view {RUN_ID} --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name: .name}'

# List failed jobs with their failed steps
gh run view {RUN_ID} --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name: .name, steps: [.steps[] | select(.conclusion == "failure") | .name]}'

5. 下载并分析日志

首选方法：

# Get failed logs (last 250 lines usually contains the error)
gh run view {RUN_ID} --log-failed 2>&1 | tail -250

# Target a specific failed job by ID
gh run view {RUN_ID} --job {JOB_ID} --log-failed 2>&1 | tail -100

日志待生成时的备用方法：

REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
gh api "/repos/${REPO}/actions/jobs/{JOB_ID}/logs"

智能日志提取（示例）：

# Context around failure markers
gh run view {RUN_ID} --log-failed 2>&1 | grep -B 5 -A 10 -iE "error|fail|exception|traceback|panic|fatal" | head -100

# Python tests - pytest summary
gh run view {RUN_ID} --log-failed 2>&1 | grep -E -A 50 "FAILED|ERROR|short test summary"

# TypeScript/ESLint errors
gh run view {RUN_ID} --log-failed 2>&1 | grep -E -B 2 -A 5 "error TS|error  "

# E2E snapshot mismatches
gh run view {RUN_ID} --log-failed 2>&1 | grep -E -B 2 -A 5 "Missing snapshot for|Snapshot mismatch for"

6. 分析失败原因

识别：

• 错误类型：Lint、类型检查、测试失败、构建错误
• 根本原因：首个/主要错误（而非连锁失败）
• 受影响的文件：哪些文件需要更改
• 错误消息：确切的错误文本

常见 CI 失败类别：

类别	工作流	Make 命令	自动修复
Python lint	python-tests.yml	make python-lint	✅ make autofix
Python 类型	python-tests.yml	make python-types	❌ 手动
Python 测试	python-tests.yml	make python-tests	❌ 手动
前端 lint	js-tests.yml	make frontend-lint	✅ make autofix
前端类型	js-tests.yml	make frontend-types	❌ 手动
前端测试	js-tests.yml	make frontend-tests	❌ 手动
E2E 测试	playwright.yml	make run-e2e-test <file>	❌ 手动
E2E 快照	playwright.yml	make run-e2e-test <file>	✅ make update-snapshots
NOTICES	js-tests.yml	make update-notices	✅ make update-notices
最低约束	python-tests.yml	make update-min-deps	✅ make update-min-deps
Pre-commit	enforce-pre-commit.yml	uv run pre-commit run --all-files	✅ 大多自动修复
相对导入	ensure-relative-imports.yml	检查脚本输出	❌ 手动
PR 标签	require-labels.yml	不适用	⏭️ 忽略

💡 快捷方式： 对于 lint/格式化失败，先运行 make autofix。

7. 呈现诊断结果

对于多个失败，列出所有失败并让用户选择：

CI Failure Analysis for PR #{NUMBER}: {TITLE}
═══════════════════════════════════════════════════════════════

Found {N} failed jobs/checks:

─────────────────────────────────────────────────────────────────

1. [LINT] Python Unit Tests → Run Linters
   Workflow: python-tests.yml (GitHub Actions)
   Error:    Ruff formatting error in lib/streamlit/elements/foo.py
   Auto-fix: ✅ `make autofix`

2. [TYPE] Javascript Unit Tests → Run type checks
   Workflow: js-tests.yml (GitHub Actions)
   Error:    TS2322: Type 'string' is not assignable to type 'number'
   File:     frontend/lib/src/components/Bar.tsx:42
   Auto-fix: ❌ Manual fix required

─────────────────────────────────────────────────────────────────

Which failures should I address?
Recommended: "1" (auto-fixable)
Options: "1" | "1,2" | "1-2" | "all" | "only auto-fixable"

对于单个失败，显示详细分析：

─────────────────────────────────────────────────────────────────
Analyzing: [TYPE] Javascript Unit Tests → Run type checks
─────────────────────────────────────────────────────────────────

Category: TYPE
Workflow: js-tests.yml
Job:      js-unit-tests (ID: 12345678)
Step:     Run type checks

Error snippet:
  frontend/lib/src/components/Bar.tsx:42:5
  error TS2322: Type 'string' is not assignable to type 'number'.

Proposed Fix:
  Change type annotation or fix the value type

─────────────────────────────────────────────────────────────────

Would you like me to:
  [1] Apply the fix automatically
  [2] Show the proposed changes first
  [3] Run local verification only
  [4] Skip this and move to next failure

8. 应用修复并在本地验证

用户批准后，应用修复并运行验证：

# Run all checks (lint, types, tests) on changed files
make check

# Python tests (specific)
uv run pytest lib/tests/path/to/test_file.py::test_name -v

# Frontend tests (specific)
cd frontend && yarn test path/to/test.test.tsx

# E2E tests
make run-e2e-test {test_file.py}

# E2E snapshots
make update-snapshots

9. 总结并推送

git status --short
git diff --stat

报告失败内容、更改内容以及本地验证结果。

git add -A
git commit -m "fix: resolve CI failure in {workflow/step}"
git push

10. 重新检查 CI 状态

gh pr checks --watch
# Or re-run failed jobs
gh run rerun {RUN_ID} --failed

规则

• 关注根本原因：首个错误，而非连锁失败
• 最小修复：能解决问题的最小更改
• 不要跳过测试：绝不要通过禁用测试来"修复" CI
• 在本地验证：始终运行适当的本地命令
• 保留意图：理解代码原本想做什么

错误处理

问题	解决方案
身份认证失败	使用 workflow/repo scope 运行 gh auth login
分支没有 PR	使用 gh run list 检查工作流运行
CI 仍在运行	gh pr checks --watch
日志待生成	使用任务日志 API 重试
没有失败的检查	全部通过 ✅
触发速率限制	等待并重试
不稳定测试	重新运行：gh run rerun {RUN_ID} --failed