" --body "<description>" # Checkout PR gh pr checkout <pr-number> # Check PR status gh pr checks <pr-number> # Update PR branch gh pr update-branch <pr-number> # Comment on PR gh pr comment <pr-number> --body "<message>" # Merge PR gh pr merge <pr-number> [--squash|--merge|--rebase] [--auto] [--delete-branch] # Close PR gh pr close <pr-number> # Reopen PR gh pr reopen <pr-number> # Mark PR ready for review gh pr ready <pr-number> ``` #### Issues ```bash # List issues gh issue list [--label <label>] [--state <state>] [--assignee <user>] # View issue gh issue view <issue-number> # Create issue gh issue create --title "<title>" --body "<body>" # Comment on issue gh issue comment <issue-number> --body "<message>" # Close issue gh issue close <issue-number> # Edit issue gh issue edit <issue-number> [--title "<title>"] [--body "<body>"] ``` #### Workflows ```bash # List workflows gh workflow list # View workflow gh workflow view <workflow-name> # Run workflow gh workflow run <workflow-name> # Enable/disable workflow gh workflow enable <workflow-name> gh workflow disable <workflow-name> ``` ### JSON Output and Parsing **Useful JSON Fields:** ```bash # Workflow runs gh run list --json databaseId,name,headBranch,conclusion,createdAt,updatedAt # Pull requests gh pr list --json number,title,state,statusCheckRollup,mergeable,labels,author # Issues gh issue list --json number,title,state,labels,assignees,createdAt # Parse with jq gh pr list --json number,title,statusCheckRollup | \ jq '.[] | select(.statusCheckRollup[].conclusion == "failure")' ``` --- ## Decision Trees ### 1. Failure Diagnosis Flow ``` Identify failed run/PR ↓ Retrieve error logs ↓ Parse error message ↓ ┌─────────────────────────────────────────────┐ │ Error Type? │ ├─────────────────────────────────────────────┤ │ Test Failure │ │ → Read test file │ │ → Identify assertion/expectation mismatch │ │ → Fix code or test │ │ → Run locally, commit, push │ ├─────────────────────────────────────────────┤ │ Build/Compile Error │ │ → Read source file at error line │ │ → Fix syntax/type/import error │ │ → Verify compilation, commit, push │ ├─────────────────────────────────────────────┤ │ Linting/Formatting │ │ → Run linter locally │ │ → Auto-fix if possible │ │ → Manual fix remaining issues │ │ → Verify, commit, push │ ├─────────────────────────────────────────────┤ │ Dependency/Installation │ │ → Check lock file consistency │ │ → Update dependencies │ │ → Regenerate lock file │ │ → Test build, commit, push │ ├─────────────────────────────────────────────┤ │ Infrastructure/Timeout │ │ → Check workflow YAML │ │ → Adjust timeout/resource limits │ │ → Optimize build if needed │ │ → Commit workflow changes │ ├─────────────────────────────────────────────┤ │ Flaky/Intermittent │ │ → Rerun without changes │ │ → If persists, investigate race condition │ │ → Add retry logic or fix timing issue │ └─────────────────────────────────────────────┘ ↓ Re-trigger workflow ↓ Verify success ``` ### 2. Dependabot Merge Strategy ``` Dependabot PR detected ↓ Extract version change from title ↓ ┌─────────────────────────────────────┐ │ Security label present? │ │ YES → Priority: CRITICAL │ │ Action: Merge immediately │ │ after checks pass │ └─────────────────────────────────────┘ ↓ NO ┌─────────────────────────────────────┐ │ Version change type? │ ├─────────────────────────────────────┤ │ PATCH (1.2.3 → 1.2.4) │ │ → Risk: LOW │ │ → Batch with other patches │ │ → Merge group together │ ├─────────────────────────────────────┤ │ MINOR (1.2.3 → 1.3.0) │ │ → Risk: MEDIUM │ │ → Check release notes │ │ → Test individually │ │ → Merge if checks pass │ ├─────────────────────────────────────┤ │ MAJOR (1.2.3 → 2.0.0) │ │ → Risk: HIGH │ │ → Read CHANGELOG/migration guide │ │ → Check for breaking changes │ │ → Flag for manual review │ │ → May require code updates │ └─────────────────────────────────────┘ ↓ Check PR status ↓ ┌─────────────────────────────────────┐ │ Conflicts? │ │ YES → Rebase on main │ │ Regenerate lock files │ │ Or: @dependabot rebase │ └─────────────────────────────────────┘ ↓ NO ┌─────────────────────────────────────┐ │ Checks passing? │ │ YES → Proceed to merge │ │ NO → Investigate failure │ │ Fix if possible │ │ Or: Close and flag │ └─────────────────────────────────────┘ ↓ Execute merge ↓ Verify merged successfully ↓ Delete branch ``` ### 3. Escalation Criteria **When to Stop and Request Manual Intervention:** ``` Issue encountered ↓ Attempt automated fix ↓ ┌─────────────────────────────────────────────┐ │ Escalate to human if: │ ├─────────────────────────────────────────────┤ │ ❌ Fix requires architectural decision │ │ ❌ Multiple failed attempts (>3) │ │ ❌ Breaking changes in major version update │ │ ❌ Security implications unclear │ │ ❌ Requires external service access │ │ ❌ Merge would overwrite others' work │ │ ❌ Repository protection rules block action │ │ ❌ Insufficient permissions │ │ ❌ Ambiguous requirements │ │ ❌ Would require force-push to shared branch│ └─────────────────────────────────────────────┘ ↓ Document findings ↓ Create issue with: - Problem description - Attempted solutions - Logs/error messages - Recommended next steps ↓ Notify team ``` --- ## Safety Guidelines ### Actions Requiring Confirmation **ALWAYS ask before:** - Force-pushing to shared branches (main, develop, release/*) - Deleting branches that aren't merged - Merging PRs without passing checks - Closing PRs without explanation - Making changes to workflow files that affect required checks - Merging major version dependency updates - Rebasing PRs with many commits - Executing bulk operations (>10 PRs/issues) **NEVER do without explicit permission:** - Force-push to main/master branch - Disable required status checks - Bypass branch protection rules - Delete the repository - Revoke access tokens - Modify GitHub Actions secrets - Change repository settings ### Rollback Procedures **If a fix causes new failures:** ```bash # 1. Identify problematic commit git log --oneline -n 5 # 2. Revert the commit git revert <commit-sha> git push # 3. Or reset if not pushed git reset --hard HEAD~1 git push --force-with-lease # Only on feature branches! # 4. Comment on PR/issue gh pr comment <pr-number> --body "Rolled back changes from commit <sha> due to <reason>. New failures: <description> Investigating alternative approach." # 5. Trigger fresh workflow run gh run rerun <run-id> ``` **If merge causes problems:** ```bash # 1. Identify merge commit git log --merges -n 5 # 2. Revert merge (if pushed to main) git revert -m 1 <merge-commit-sha> git push # 3. Document rollback gh issue create --title "Rollback: <PR title>" \ --body "Reverted PR #<number> due to: - <issue-1> - <issue-2> Original PR will be updated and re-merged after fixes." ``` ### What NOT to Automate **Manual review required for:** - Major version bumps with breaking changes - Security vulnerability fixes that change APIs - Changes to authentication/authorization logic - Database migrations - Infrastructure as Code changes (Terraform, CloudFormation) - Changes to CI/CD pipelines that affect deployment - Dependency updates in production-critical services - Modifications to .github/workflows files that affect required checks - PRs from external contributors in public repos **Criteria for manual review:** - Business logic changes - Performance-critical code - Customer-facing features - Regulatory compliance requirements - Multi-service coordination needed - Requires domain expertise --- ## Examples ### Example 1: Fix Failing Test in CI **Scenario**: Go test suite fails on main branch ```bash # 1. Identify failure $ gh run list --status failure --limit 5 ✗ CI feat: add new API endpoint main 1234567 about 5 minutes ago # 2. View failure logs $ gh run view 1234567 --log-failed Test: TestAPIEndpoint/POST_request Error: Expected status 200, got 500 FAIL github.com/example/repo/internal/api # 3. Checkout main branch $ git checkout main $ git pull # 4. Read the failing test $ cat internal/api/endpoint_test.go # [Analyze test expectations] # 5. Read the implementation $ cat internal/api/endpoint.go # [Identify bug: missing error handling] # 6. Fix the issue $ cat > internal/api/endpoint.go << 'EOF' func HandlePost(w http.ResponseWriter, r *http.Request) { var data RequestData if err := json.NewDecoder(r.Body).Decode(&data); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return // FIX: Was missing return, causing 500 error } // ... rest of handler } EOF # 7. Verify locally $ go test ./internal/api/... PASS # 8. Commit and push $ git add internal/api/endpoint.go $ git commit -m "fix: add missing return after error in POST handler Fixes GitHub Actions run #1234567 Root cause: Missing return statement after error response caused subsequent code to execute and panic. Changes: - Added return after BadRequest error in HandlePost - Verified with: go test ./internal/api/..." $ git push origin main # 9. Verify CI passes $ gh run watch ✓ CI fix: add missing return after error in POST handler main 1234568 passed ``` ### Example 2: Resolve Dependabot Conflicts **Scenario**: Multiple Dependabot PRs have merge conflicts ```bash # 1. List Dependabot PRs $ gh pr list --author "app/dependabot" #42 Bump golang from 1.23-alpine to 1.25-alpine #41 Bump github.com/stretchr/testify from 1.8.0 to 1.9.0 #40 Bump golang.org/x/oauth2 from 0.15.0 to 0.16.0 # 2. Check for conflicts $ gh pr view 42 --json mergeable {"mergeable": "CONFLICTING"} # 3. Checkout PR $ gh pr checkout 42 remote: Enumerating objects: 5, done. Switched to branch 'dependabot/docker/golang-1.25-alpine' # 4. Rebase on main $ git fetch origin main $ git rebase origin/main Auto-merging go.mod CONFLICT (content): Merge conflict in go.mod # 5. Resolve conflict in go.mod $ cat go.mod <<<<<<< HEAD go 1.23 ======= go 1.25 >>>>>>> Bump golang from 1.23-alpine to 1.25-alpine # Accept Dependabot's version $ cat > go.mod << 'EOF' module github.com/example/repo go 1.25 require ( // ... dependencies ) EOF # 6. Regenerate go.sum $ go mod tidy # 7. Verify build $ make build $ make test # 8. Complete rebase $ git add go.mod go.sum $ git rebase --continue $ git push --force-with-lease # 9. Verify checks pass $ gh pr checks 42 ✓ CI - Build and Test ✓ CodeQL ✓ Dependency Review # 10. Enable auto-merge $ gh pr merge 42 --auto --squash Pull request #42 will be automatically merged when all requirements are met # 11. Repeat for other Dependabot PRs ``` ### Example 3: Batch Merge Compatible Updates **Scenario**: Merge multiple safe Dependabot patch updates ```bash # 1. Identify patch updates $ gh pr list --author "app/dependabot" --json number,title | \ jq -r '.[] | select(.title | contains("Bump @types")) | "\(.number): \(.title)"' 45: Bump @types/node from 20.10.0 to 20.10.5 44: Bump @types/react from 18.2.0 to 18.2.4 43: Bump @types/jest from 29.5.0 to 29.5.1 # 2. Verify all checks passing $ for pr in 45 44 43; do echo "PR #$pr:" gh pr checks $pr --json state,conclusion | \ jq -r '.[] | "\(.state): \(.conclusion)"' done PR #45: COMPLETED: SUCCESS PR #44: COMPLETED: SUCCESS PR #43: COMPLETED: SUCCESS # 3. Check for conflicts $ for pr in 45 44 43; do mergeable=$(gh pr view $pr --json mergeable -q .mergeable) echo "PR #$pr: $mergeable" done PR #45: MERGEABLE PR #44: MERGEABLE PR #43: MERGEABLE # 4. Auto-merge all $ for pr in 45 44 43; do gh pr merge $pr --auto --squash --delete-branch echo "✓ PR #$pr queued for auto-merge" done ✓ PR #45 queued for auto-merge ✓ PR #44 queued for auto-merge ✓ PR #43 queued for auto-merge # 5. Monitor merge progress $ watch -n 5 'gh pr list --author "app/dependabot" --json number,state,merged' # 6. Verify all merged $ gh pr list --author "app/dependabot" --state merged --limit 5 ✓ #45 Bump @types/node from 20.10.0 to 20.10.5 (merged 2m ago) ✓ #44 Bump @types/react from 18.2.0 to 18.2.4 (merged 3m ago) ✓ #43 Bump @types/jest from 29.5.0 to 29.5.1 (merged 4m ago) ``` ### Example 4: Comprehensive Repository Triage **Scenario**: Clean up accumulated technical debt ```bash # 1. Create triage issue $ gh issue create --title "Repository Maintenance - $(date +%Y-%m-%d)" --body " ## GitHub Maintenance Triage **Created**: $(date) **Status**: In Progress ### Failed Workflows $(gh run list --status failure --limit 10 --json name,conclusion,createdAt | \ jq -r '.[] | "- [ ] \(.name) - \(.conclusion) (\(.createdAt))"') ### Failed PRs $(gh pr list --search "status:failure" --json number,title | \ jq -r '.[] | "- [ ] #\(.number): \(.title)"') ### Dependabot Backlog $(gh pr list --author "app/dependabot" --json number,title | \ jq -r '.[] | "- [ ] #\(.number): \(.title)"') " Created issue #123 # 2. Prioritize issues # P0: Main branch CI failure (#1234567) # P1: Feature PR blocked (#87) # P2: 12 Dependabot PRs # 3. Fix P0: Main branch CI $ gh run view 1234567 --log-failed > failure.log $ cat failure.log | grep -A 5 "FAILED" # [Implement fix as in Example 1] $ gh issue comment 123 --body "✅ **P0 Fixed**: Main branch CI - Root cause: Test timeout - Fix: Increased timeout, optimized test setup - Verification: Run #1234580 passed" # 4. Fix P1: Feature PR $ gh pr checkout 87 $ gh pr checks 87 # [Implement fixes as in Example 2] $ gh issue comment 123 --body "✅ **P1 Fixed**: Feature PR #87 unblocked - Fixed linting issues - Resolved merge conflicts - All checks passing, ready for review" # 5. Handle P2: Dependabot backlog # [Batch process as in Example 3] $ gh issue comment 123 --body "✅ **P2 Progress**: Dependabot cleanup - Merged 8 patch updates (auto-merge) - Merged 3 minor updates after testing - Flagged 1 major update for manual review (#92)" # 6. Summary $ gh issue comment 123 --body "## Triage Complete **Summary**: - ✅ 1 critical CI failure resolved - ✅ 1 feature PR unblocked - ✅ 11/12 Dependabot PRs merged - ⏳ 1 major version upgrade awaiting review (#92) **Time saved**: ~3 hours of manual work **Next steps**: Review major version upgrade #92" $ gh issue close 123 ``` --- ## Error Handling ### Common Failure Modes #### 1. Authentication Failures **Error:** ``` gh: authentication failed ``` **Recovery:** ```bash # Check authentication status $ gh auth status # Re-authenticate $ gh auth login # Refresh token $ gh auth refresh ``` #### 2. Permission Denied **Error:** ``` Resource not accessible by personal access token ``` **Recovery:** ```bash # Check required scopes $ gh auth status # Token needs these scopes: # - repo (full control) # - workflow (update GitHub Actions) # - write:packages (if using container registry) # Re-authenticate with correct scopes $ gh auth refresh -h github.com -s repo,workflow ``` #### 3. Workflow Not Found **Error:** ``` could not find workflow run: 404 Not Found ``` **Recovery:** ```bash # List recent runs to find correct ID $ gh run list --limit 20 # Verify run ID exists $ gh api repos/{owner}/{repo}/actions/runs/{run-id} # If run too old, it may be archived - use workflow name $ gh workflow view "CI" --limit 50 ``` #### 4. Merge Conflicts **Error:** ``` merge conflict in <file> ``` **Recovery:** ```bash # Abort merge $ git merge --abort # Or resolve conflicts: $ git status # Edit conflicted files, remove markers $ git add <resolved-files> $ git commit # Or use --theirs for lock files $ git checkout --theirs package-lock.json $ npm install $ git add package-lock.json $ git commit ``` #### 5. Rate Limiting **Error:** ``` API rate limit exceeded ``` **Recovery:** ```bash # Check rate limit status $ gh api rate_limit # Wait for rate limit reset $ gh api rate_limit | jq .resources.core.reset # Or use authenticated requests (higher limit) $ gh auth login # Increases limit from 60/hr to 5000/hr ``` ### Recovery Strategies #### Strategy 1: Retry with Backoff ```bash # For transient failures retry_count=0 max_retries=3 while [ $retry_count -lt $max_retries ]; do if gh run rerun <run-id>; then echo "Success!" break else retry_count=$((retry_count + 1)) wait_time=$((2 ** retry_count)) echo "Retry $retry_count/$max_retries after ${wait_time}s..." sleep $wait_time fi done ``` #### Strategy 2: Fallback to API ```bash # If gh CLI fails, use direct API gh api repos/{owner}/{repo}/actions/runs/{run-id}/rerun \ -X POST \ --silent ``` #### Strategy 3: Graceful Degradation ```bash # If automated fix fails, document for manual intervention if ! make test; then gh pr comment <pr-number> --body "⚠️ Automated fix attempted but tests still failing. **Error:** \`\`\` $(make test 2>&1 | tail -20) \`\`\` Manual review required. See logs for details." exit 1 fi ``` ### When to Abort **Abort execution if:** - ❌ Exceeded maximum retry attempts (default: 3) - ❌ Detected circular dependency in fixes - ❌ Working directory becomes dirty unexpectedly - ❌ GitHub API returns 403 Forbidden (not just rate limit) - ❌ Would cause data loss (force-push to protected branch) - ❌ Cannot verify current state (git status fails) **Abort procedure:** ```bash # 1. Stop all operations # 2. Document state echo "ABORTED: $(date)" > abort-state.log git status >> abort-state.log gh run list --limit 5 >> abort-state.log # 3. Revert any partial changes git reset --hard HEAD git clean -fd # 4. Create issue with diagnostic info gh issue create --title "Automated maintenance aborted" \ --body "$(cat abort-state.log)" \ --label "automation-failure" # 5. Notify user echo "❌ Automation aborted. See issue for details." ``` --- ## Best Practices ### Before You Start 1. **Verify setup**: ```bash gh auth status git status make test # Ensure baseline works ``` 2. **Create tracking issue** for audit trail 3. **Understand repository conventions**: - Branch naming (feat/, fix/, chore/) - Commit message format - PR merge strategy (squash vs merge) ### During Execution 1. **Small, focused commits**: One fix per commit 2. **Descriptive messages**: Include run/PR numbers 3. **Test before push**: Run tests locally when possible 4. **Comment proactively**: Explain automated actions 5. **Monitor progress**: Use `gh run watch` and `gh pr checks` ### After Completion 1. **Verify all changes merged** 2. **Close tracking issues** 3. **Clean up branches**: Delete merged branches 4. **Document patterns**: Note recurring issues for prevention --- ## Skill Activation To use this skill, simply say: - "Fix failing GitHub Actions" - "Clean up Dependabot PRs" - "Resolve PR #123 check failures" - "Triage repository issues" Claude Code will then: 1. Assess the current state using `gh` commands 2. Prioritize issues by severity 3. Systematically fix issues following this skill's workflows 4. Document all actions taken 5. Verify resolutions 6. Provide summary report **Remember**: This skill automates mechanical tasks but escalates complex decisions to you. You stay in control while saving hours of manual work.

# Github Issue Resolver > Strategically resolves GitHub Actions failures, failed pull requests, and Dependabot issues using the gh CLI with intelligent analysis and automated fixes. - Skill: `diegosouzapw/github-issue-resolver` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/github-issue-resolver` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/github-issue-resolver/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/diegosouzapw/github-issue-resolver --- # GitHub Issue Resolver Skill ## Overview This skill enables Claude Code to systematically diagnose and resolve GitHub repository maintenance issues, including: - **GitHub Actions failures**: Analyze logs, identify root causes, implement fixes, and re-trigger workflows - **Failed pull requests**: Checkout branches, fix check failures, resolve conflicts, and manage reviews - **Dependabot issues**: Evaluate dependency updates, resolve conflicts, and strategically merge compatible updates - **Strategic triage**: Prioritize issues by severity and impact, create systematic workflows ### Prerequisites Before using this skill, ensure: - ✅ GitHub CLI (`gh`) is installed and authenticated (`gh auth status`) - ✅ You have write access to the target repository - ✅ Git is configured with proper user credentials - ✅ You're in a valid git repository directory - ✅ Working directory is clean or changes are stashed ### Capabilities This skill provides: - Automated log analysis and error pattern recognition - Intelligent root cause diagnosis for CI/CD failures - Code-aware fixes for test failures, linting issues, and build errors - Strategic batching of dependency updates - Audit trail documentation with PR comments - Safe rollback procedures --- ## When to Use This Skill Activate this skill with any of these phrases: - "Fix the failing GitHub Actions" - "Resolve failed CI/CD runs" - "Handle failed pull requests" - "Manage Dependabot PRs" - "Triage GitHub issues" - "Fix failing checks on PR #123" - "Resolve all Dependabot conflicts" - "Clean up failed workflow runs" **Triggering Scenarios:** - CI/CD pipeline shows red status indicators - Pull requests blocked by failed checks - Multiple Dependabot PRs pending with conflicts - Repository has accumulated technical debt from failed automation - Need systematic cleanup before a release - After bulk dependency updates or major refactors --- ## Core Workflows ### 1. GitHub Actions Failure Resolution **Objective**: Identify, diagnose, and fix failed workflow runs. #### Step 1: List Failed Runs ```bash # List recent failed runs gh run list --status failure --limit 10 # List failed runs for specific workflow gh run list --workflow "CI" --status failure --limit 5 # Get JSON output for programmatic processing gh run list --status failure --json databaseId,name,headBranch,conclusion,createdAt --limit 10 ``` #### Step 2: Analyze Failure Logs ```bash # View summary of failed run gh run view # Get detailed logs for failed jobs only gh run view --log-failed # Download all logs for offline analysis gh run view --log-failed > failure-logs.txt ``` #### Step 3: Diagnose Root Cause **Common Failure Patterns:** | Error Pattern | Root Cause | Action Required | |---------------|------------|-----------------| | `npm test failed` | Test failures | Fix failing tests or test setup | | `golangci-lint` errors | Code quality issues | Fix linting violations | | `go build` failed | Compilation errors | Fix syntax/type errors | | `docker build` failed | Dockerfile or dependency issues | Fix Dockerfile, update dependencies | | `Error: No space left on device` | Runner disk space | Clean up artifacts, optimize build | | `Error: Process completed with exit code 137` | OOM (Out of Memory) | Reduce memory usage or increase limits | | `unable to access 'https://...'` | Network/auth issues | Check credentials, retry | **Diagnostic Process:** 1. Read the full log output 2. Identify the failing step and error message 3. Trace back to root cause (not just symptom) 4. Check if issue is environment-specific or code-specific 5. Determine if fix is needed in: - Source code - Test files - Workflow YAML - Dependencies - Configuration files #### Step 4: Implement Fix **Decision Tree:** ``` Is the failure in source code? ├─ YES → Read affected files, implement fix, run tests locally if possible └─ NO → Is it in workflow configuration? ├─ YES → Edit .github/workflows/*.yml, validate YAML syntax └─ NO → Is it a dependency issue? ├─ YES → Update package.json/go.mod/requirements.txt └─ NO → Document issue, escalate for manual review ``` **Implementation Pattern:** ```bash # 1. Identify files needing changes from error logs # 2. Read relevant files # 3. Make targeted fixes # 4. Commit changes with descriptive message git add git commit -m "fix: resolve in Fixes GitHub Actions run # Root cause: Changes: " # 5. Push changes git push origin ``` #### Step 5: Re-trigger and Verify ```bash # Re-run failed jobs gh run rerun --failed # Watch run progress gh run watch # Verify success gh run view ``` **Success Criteria:** - ✅ All jobs complete with green status - ✅ No new failures introduced - ✅ Fix is committed with clear message - ✅ Logs show expected behavior --- ### 2. Failed Pull Request Management **Objective**: Fix PRs blocked by failed checks or conflicts. #### Step 1: List and Prioritize PRs ```bash # List all PRs with checks gh pr list --json number,title,author,statusCheckRollup # List PRs with failed checks gh pr list --search "status:failure" # List PRs by specific author (e.g., Dependabot) gh pr list --author "app/dependabot" # Get detailed PR information gh pr view --json number,title,statusCheckRollup,mergeable ``` **Prioritization Order:** 1. **Critical**: Security patches, breaking production builds 2. **High**: Feature PRs blocking other work, main branch protection failures 3. **Medium**: Routine updates with failed tests 4. **Low**: Minor dependency updates, documentation changes #### Step 2: Checkout and Analyze ```bash # Checkout PR branch locally gh pr checkout # View PR status and checks gh pr checks # View detailed check information gh pr view ``` #### Step 3: Fix Check Failures **Common Scenarios:** **Scenario A: Failed Tests** ```bash # 1. Identify failing tests from check output gh pr checks # 2. Run tests locally make test # or appropriate test command # 3. Fix failing tests # [Read test files, identify issues, implement fixes] # 4. Verify locally make test # 5. Commit and push git add . git commit -m "fix: resolve test failures in PR #" git push ``` **Scenario B: Merge Conflicts** ```bash # 1. Update branch with base gh pr update-branch # If conflicts exist: # 2. Fetch latest git fetch origin # 3. Merge base branch git merge origin/main # or origin/master # 4. Resolve conflicts # [Read conflicted files, resolve markers, test] # 5. Complete merge git add . git commit -m "fix: resolve merge conflicts with main" git push ``` **Scenario C: Linting/Formatting Issues** ```bash # 1. Run linter locally make lint # or golangci-lint run, npm run lint, etc. # 2. Auto-fix if possible make lint-fix # or appropriate fix command # 3. Manual fixes for remaining issues # [Read files, fix violations] # 4. Verify and commit make lint git add . git commit -m "fix: resolve linting issues in PR #" git push ``` #### Step 4: Document and Request Review ```bash # Add comment explaining fixes gh pr comment --body "Fixed check failures: - Resolved test failures in pkg/clients/kubernetes_test.go - Updated linting issues in internal/server/server.go - Rebased on latest main to resolve conflicts All checks now passing. Ready for review." # Request review if needed gh pr edit --add-reviewer # Mark as ready for review (if draft) gh pr ready ``` #### Step 5: Merge When Ready ```bash # Check merge eligibility gh pr view --json mergeable,mergeStateStatus # Merge if all checks pass gh pr merge --auto --squash # or --merge, --rebase # Verify merge gh pr view --json state,merged ``` --- ### 3. Dependabot Issue Handling **Objective**: Efficiently manage automated dependency updates. #### Step 1: Identify Dependabot PRs ```bash # List all Dependabot PRs gh pr list --author "app/dependabot" --json number,title,headRefName,statusCheckRollup # Group by dependency type gh pr list --author "app/dependabot" --json title | jq -r '.[].title' | sort # Identify PRs with conflicts or failed checks gh pr list --author "app/dependabot" --search "status:failure" ``` #### Step 2: Categorize Updates **Semantic Versioning Analysis:** | Update Type | Example | Risk Level | Strategy | |-------------|---------|------------|----------| | **Patch** | 1.2.3 → 1.2.4 | Low | Batch merge | | **Minor** | 1.2.3 → 1.3.0 | Medium | Test individually | | **Major** | 1.2.3 → 2.0.0 | High | Manual review required | | **Security** | Any with security label | Critical | Immediate priority | **Categorization Process:** ```bash # For each Dependabot PR, extract version change from title # Example: "Bump golang from 1.23-alpine to 1.25-alpine" # - Package: golang # - From: 1.23 # - To: 1.25 # - Type: Minor version bump # Check for security labels gh pr view --json labels # Check for breaking changes in release notes gh pr view --json body ``` #### Step 3: Strategic Batching **Batch Merge Decision Tree:** ``` Is this a security update? ├─ YES → Merge immediately after checks pass └─ NO → Is this a patch version? ├─ YES → Safe to batch with other patches └─ NO → Is this a minor version? ├─ YES → Can batch if same dependency ecosystem and checks pass └─ NO → Major version → Review breaking changes, merge individually ``` **Batching Strategy:** ```bash # Batch 1: All patch updates for same package manager # Example: npm patches gh pr list --author "app/dependabot" --search "Bump @types" --json number # Batch 2: Security updates (highest priority) gh pr list --author "app/dependabot" --label "security" --json number # Batch 3: Minor updates with passing checks gh pr list --author "app/dependabot" --search "Bump" --json number,statusCheckRollup ``` #### Step 4: Resolve Dependabot Conflicts **Conflict Resolution Pattern:** ```bash # 1. Checkout Dependabot PR gh pr checkout # 2. Rebase on latest main git fetch origin main git rebase origin/main # 3. If conflicts in lock files (package-lock.json, go.sum, etc.) # Accept Dependabot's changes and regenerate # For npm: git checkout --theirs package-lock.json npm install # For Go: git checkout --theirs go.sum go mod tidy # For Python: git checkout --theirs poetry.lock poetry lock --no-update # 4. Verify build still works make build && make test # 5. Complete rebase git add . git rebase --continue git push --force-with-lease # 6. Ask Dependabot to rebase (alternative) gh pr comment --body "@dependabot rebase" ``` #### Step 5: Use Dependabot Commands **Dependabot Command Reference:** ```bash # Rebase PR to resolve conflicts gh pr comment --body "@dependabot rebase" # Recreate PR gh pr comment --body "@dependabot recreate" # Merge PR (if auto-merge enabled) gh pr comment --body "@dependabot merge" # Squash and merge gh pr comment --body "@dependabot squash and merge" # Ignore this dependency gh pr comment --body "@dependabot ignore this dependency" # Ignore this major version gh pr comment --body "@dependabot ignore this major version" ``` #### Step 6: Validate and Merge **Validation Checklist:** - [ ] All checks passing - [ ] No merge conflicts - [ ] Lock files regenerated correctly - [ ] Build succeeds locally - [ ] Tests pass - [ ] No unexpected dependency additions - [ ] Security vulnerabilities resolved (if applicable) **Merge Execution:** ```bash # Enable auto-merge for Dependabot PRs with passing checks gh pr merge --auto --squash # Or merge immediately gh pr merge --squash --delete-branch # Batch merge multiple PRs for pr in ; do gh pr merge $pr --auto --squash done ``` --- ### 4. Priority Triage System **Objective**: Systematically process multiple issues in optimal order. #### Triage Workflow **Phase 1: Discovery** ```bash # Get comprehensive view of repository health gh run list --status failure --limit 20 gh pr list --search "status:failure" gh issue list --label "bug" --state open # Export to structured format gh run list --status failure --json databaseId,name,conclusion,createdAt > failed-runs.json gh pr list --json number,title,statusCheckRollup,labels > prs.json ``` **Phase 2: Categorization** **Priority Matrix:** | Priority | Criteria | Examples | Action Timeframe | |----------|----------|----------|------------------| | **P0** | Production broken, security vulnerabilities | Main branch build failing, CVE patches | Immediate | | **P1** | Blocking work, failing releases | Feature branch CI broken, release workflow failed | Today | | **P2** | Non-blocking failures | Dependabot minor updates with conflicts | This week | | **P3** | Minor issues, documentation | Linting in draft PRs, doc build warnings | When time permits | **Phase 3: Execution Plan** ```bash # Create ordered task list based on priority # Execute in sequence: # 1. P0: Fix main branch # 2. P1: Unblock feature work # 3. P2: Clean up Dependabot backlog # 4. P3: Housekeeping # Track progress with comments gh issue create --title "GitHub Maintenance - $(date +%Y-%m-%d)" \ --body "## Triage Summary **P0 Issues:** - [ ] Fix main branch CI (#) - [ ] Merge security patch (#) **P1 Issues:** - [ ] Fix feature PR # - [ ] Resolve workflow timeout **P2 Issues:** - [ ] Merge 5 Dependabot PRs - [ ] Update outdated workflows **P3 Issues:** - [ ] Clean up stale branches - [ ] Update documentation" ``` **Phase 4: Execution** Follow workflows 1-3 above for each issue, documenting progress: ```bash # After each fix, update tracking issue gh issue comment --body "✅ Completed: Fixed main branch CI - Root cause: Test timeout in integration suite - Fix: Increased timeout from 5m to 10m - Verification: Run # passed" ``` **Phase 5: Summary Report** ```bash # After session, create summary gh issue comment --body "## Session Summary **Resolved:** - ✅ 3 failed workflow runs fixed - ✅ 5 Dependabot PRs merged - ✅ 2 feature PRs unblocked **Pending:** - ⏳ 1 major version upgrade needs manual review - ⏳ 2 PRs waiting for external review **Metrics:** - Time saved: ~2 hours of manual work - Issues closed: 8 - Success rate: 90%" ``` --- ## Command Reference ### Essential gh CLI Commands #### Repository Information ```bash # View repository details gh repo view # Clone repository gh repo clone / # Fork repository gh repo fork / ``` #### Workflow Runs ```bash # List runs gh run list [--workflow ] [--status ] [--limit ] # View run details gh run view [--log] [--log-failed] # Rerun workflows gh run rerun [--failed] # Rerun only failed jobs gh run rerun # Rerun all jobs # Watch run progress gh run watch # Download run artifacts gh run download # Cancel run gh run cancel ``` #### Pull Requests ```bash # List PRs gh pr list [--author ] [--label ] [--search ] # View PR details gh pr view [--json ] # Create PR gh pr create --title "" --body "<description>" # Checkout PR gh pr checkout <pr-number> # Check PR status gh pr checks <pr-number> # Update PR branch gh pr update-branch <pr-number> # Comment on PR gh pr comment <pr-number> --body "<message>" # Merge PR gh pr merge <pr-number> [--squash|--merge|--rebase] [--auto] [--delete-branch] # Close PR gh pr close <pr-number> # Reopen PR gh pr reopen <pr-number> # Mark PR ready for review gh pr ready <pr-number> ``` #### Issues ```bash # List issues gh issue list [--label <label>] [--state <state>] [--assignee <user>] # View issue gh issue view <issue-number> # Create issue gh issue create --title "<title>" --body "<body>" # Comment on issue gh issue comment <issue-number> --body "<message>" # Close issue gh issue close <issue-number> # Edit issue gh issue edit <issue-number> [--title "<title>"] [--body "<body>"] ``` #### Workflows ```bash # List workflows gh workflow list # View workflow gh workflow view <workflow-name> # Run workflow gh workflow run <workflow-name> # Enable/disable workflow gh workflow enable <workflow-name> gh workflow disable <workflow-name> ``` ### JSON Output and Parsing **Useful JSON Fields:** ```bash # Workflow runs gh run list --json databaseId,name,headBranch,conclusion,createdAt,updatedAt # Pull requests gh pr list --json number,title,state,statusCheckRollup,mergeable,labels,author # Issues gh issue list --json number,title,state,labels,assignees,createdAt # Parse with jq gh pr list --json number,title,statusCheckRollup | \ jq '.[] | select(.statusCheckRollup[].conclusion == "failure")' ``` --- ## Decision Trees ### 1. Failure Diagnosis Flow ``` Identify failed run/PR ↓ Retrieve error logs ↓ Parse error message ↓ ┌─────────────────────────────────────────────┐ │ Error Type? │ ├─────────────────────────────────────────────┤ │ Test Failure │ │ → Read test file │ │ → Identify assertion/expectation mismatch │ │ → Fix code or test │ │ → Run locally, commit, push │ ├─────────────────────────────────────────────┤ │ Build/Compile Error │ │ → Read source file at error line │ │ → Fix syntax/type/import error │ │ → Verify compilation, commit, push │ ├─────────────────────────────────────────────┤ │ Linting/Formatting │ │ → Run linter locally │ │ → Auto-fix if possible │ │ → Manual fix remaining issues │ │ → Verify, commit, push │ ├─────────────────────────────────────────────┤ │ Dependency/Installation │ │ → Check lock file consistency │ │ → Update dependencies │ │ → Regenerate lock file │ │ → Test build, commit, push │ ├─────────────────────────────────────────────┤ │ Infrastructure/Timeout │ │ → Check workflow YAML │ │ → Adjust timeout/resource limits │ │ → Optimize build if needed │ │ → Commit workflow changes │ ├─────────────────────────────────────────────┤ │ Flaky/Intermittent │ │ → Rerun without changes │ │ → If persists, investigate race condition │ │ → Add retry logic or fix timing issue │ └─────────────────────────────────────────────┘ ↓ Re-trigger workflow ↓ Verify success ``` ### 2. Dependabot Merge Strategy ``` Dependabot PR detected ↓ Extract version change from title ↓ ┌─────────────────────────────────────┐ │ Security label present? │ │ YES → Priority: CRITICAL │ │ Action: Merge immediately │ │ after checks pass │ └─────────────────────────────────────┘ ↓ NO ┌─────────────────────────────────────┐ │ Version change type? │ ├─────────────────────────────────────┤ │ PATCH (1.2.3 → 1.2.4) │ │ → Risk: LOW │ │ → Batch with other patches │ │ → Merge group together │ ├─────────────────────────────────────┤ │ MINOR (1.2.3 → 1.3.0) │ │ → Risk: MEDIUM │ │ → Check release notes │ │ → Test individually │ │ → Merge if checks pass │ ├─────────────────────────────────────┤ │ MAJOR (1.2.3 → 2.0.0) │ │ → Risk: HIGH │ │ → Read CHANGELOG/migration guide │ │ → Check for breaking changes │ │ → Flag for manual review │ │ → May require code updates │ └─────────────────────────────────────┘ ↓ Check PR status ↓ ┌─────────────────────────────────────┐ │ Conflicts? │ │ YES → Rebase on main │ │ Regenerate lock files │ │ Or: @dependabot rebase │ └─────────────────────────────────────┘ ↓ NO ┌─────────────────────────────────────┐ │ Checks passing? │ │ YES → Proceed to merge │ │ NO → Investigate failure │ │ Fix if possible │ │ Or: Close and flag │ └─────────────────────────────────────┘ ↓ Execute merge ↓ Verify merged successfully ↓ Delete branch ``` ### 3. Escalation Criteria **When to Stop and Request Manual Intervention:** ``` Issue encountered ↓ Attempt automated fix ↓ ┌─────────────────────────────────────────────┐ │ Escalate to human if: │ ├─────────────────────────────────────────────┤ │ ❌ Fix requires architectural decision │ │ ❌ Multiple failed attempts (>3) │ │ ❌ Breaking changes in major version update │ │ ❌ Security implications unclear │ │ ❌ Requires external service access │ │ ❌ Merge would overwrite others' work │ │ ❌ Repository protection rules block action │ │ ❌ Insufficient permissions │ │ ❌ Ambiguous requirements │ │ ❌ Would require force-push to shared branch│ └─────────────────────────────────────────────┘ ↓ Document findings ↓ Create issue with: - Problem description - Attempted solutions - Logs/error messages - Recommended next steps ↓ Notify team ``` --- ## Safety Guidelines ### Actions Requiring Confirmation **ALWAYS ask before:** - Force-pushing to shared branches (main, develop, release/*) - Deleting branches that aren't merged - Merging PRs without passing checks - Closing PRs without explanation - Making changes to workflow files that affect required checks - Merging major version dependency updates - Rebasing PRs with many commits - Executing bulk operations (>10 PRs/issues) **NEVER do without explicit permission:** - Force-push to main/master branch - Disable required status checks - Bypass branch protection rules - Delete the repository - Revoke access tokens - Modify GitHub Actions secrets - Change repository settings ### Rollback Procedures **If a fix causes new failures:** ```bash # 1. Identify problematic commit git log --oneline -n 5 # 2. Revert the commit git revert <commit-sha> git push # 3. Or reset if not pushed git reset --hard HEAD~1 git push --force-with-lease # Only on feature branches! # 4. Comment on PR/issue gh pr comment <pr-number> --body "Rolled back changes from commit <sha> due to <reason>. New failures: <description> Investigating alternative approach." # 5. Trigger fresh workflow run gh run rerun <run-id> ``` **If merge causes problems:** ```bash # 1. Identify merge commit git log --merges -n 5 # 2. Revert merge (if pushed to main) git revert -m 1 <merge-commit-sha> git push # 3. Document rollback gh issue create --title "Rollback: <PR title>" \ --body "Reverted PR #<number> due to: - <issue-1> - <issue-2> Original PR will be updated and re-merged after fixes." ``` ### What NOT to Automate **Manual review required for:** - Major version bumps with breaking changes - Security vulnerability fixes that change APIs - Changes to authentication/authorization logic - Database migrations - Infrastructure as Code changes (Terraform, CloudFormation) - Changes to CI/CD pipelines that affect deployment - Dependency updates in production-critical services - Modifications to .github/workflows files that affect required checks - PRs from external contributors in public repos **Criteria for manual review:** - Business logic changes - Performance-critical code - Customer-facing features - Regulatory compliance requirements - Multi-service coordination needed - Requires domain expertise --- ## Examples ### Example 1: Fix Failing Test in CI **Scenario**: Go test suite fails on main branch ```bash # 1. Identify failure $ gh run list --status failure --limit 5 ✗ CI feat: add new API endpoint main 1234567 about 5 minutes ago # 2. View failure logs $ gh run view 1234567 --log-failed Test: TestAPIEndpoint/POST_request Error: Expected status 200, got 500 FAIL github.com/example/repo/internal/api # 3. Checkout main branch $ git checkout main $ git pull # 4. Read the failing test $ cat internal/api/endpoint_test.go # [Analyze test expectations] # 5. Read the implementation $ cat internal/api/endpoint.go # [Identify bug: missing error handling] # 6. Fix the issue $ cat > internal/api/endpoint.go << 'EOF' func HandlePost(w http.ResponseWriter, r *http.Request) { var data RequestData if err := json.NewDecoder(r.Body).Decode(&data); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return // FIX: Was missing return, causing 500 error } // ... rest of handler } EOF # 7. Verify locally $ go test ./internal/api/... PASS # 8. Commit and push $ git add internal/api/endpoint.go $ git commit -m "fix: add missing return after error in POST handler Fixes GitHub Actions run #1234567 Root cause: Missing return statement after error response caused subsequent code to execute and panic. Changes: - Added return after BadRequest error in HandlePost - Verified with: go test ./internal/api/..." $ git push origin main # 9. Verify CI passes $ gh run watch ✓ CI fix: add missing return after error in POST handler main 1234568 passed ``` ### Example 2: Resolve Dependabot Conflicts **Scenario**: Multiple Dependabot PRs have merge conflicts ```bash # 1. List Dependabot PRs $ gh pr list --author "app/dependabot" #42 Bump golang from 1.23-alpine to 1.25-alpine #41 Bump github.com/stretchr/testify from 1.8.0 to 1.9.0 #40 Bump golang.org/x/oauth2 from 0.15.0 to 0.16.0 # 2. Check for conflicts $ gh pr view 42 --json mergeable {"mergeable": "CONFLICTING"} # 3. Checkout PR $ gh pr checkout 42 remote: Enumerating objects: 5, done. Switched to branch 'dependabot/docker/golang-1.25-alpine' # 4. Rebase on main $ git fetch origin main $ git rebase origin/main Auto-merging go.mod CONFLICT (content): Merge conflict in go.mod # 5. Resolve conflict in go.mod $ cat go.mod <<<<<<< HEAD go 1.23 ======= go 1.25 >>>>>>> Bump golang from 1.23-alpine to 1.25-alpine # Accept Dependabot's version $ cat > go.mod << 'EOF' module github.com/example/repo go 1.25 require ( // ... dependencies ) EOF # 6. Regenerate go.sum $ go mod tidy # 7. Verify build $ make build $ make test # 8. Complete rebase $ git add go.mod go.sum $ git rebase --continue $ git push --force-with-lease # 9. Verify checks pass $ gh pr checks 42 ✓ CI - Build and Test ✓ CodeQL ✓ Dependency Review # 10. Enable auto-merge $ gh pr merge 42 --auto --squash Pull request #42 will be automatically merged when all requirements are met # 11. Repeat for other Dependabot PRs ``` ### Example 3: Batch Merge Compatible Updates **Scenario**: Merge multiple safe Dependabot patch updates ```bash # 1. Identify patch updates $ gh pr list --author "app/dependabot" --json number,title | \ jq -r '.[] | select(.title | contains("Bump @types")) | "\(.number): \(.title)"' 45: Bump @types/node from 20.10.0 to 20.10.5 44: Bump @types/react from 18.2.0 to 18.2.4 43: Bump @types/jest from 29.5.0 to 29.5.1 # 2. Verify all checks passing $ for pr in 45 44 43; do echo "PR #$pr:" gh pr checks $pr --json state,conclusion | \ jq -r '.[] | "\(.state): \(.conclusion)"' done PR #45: COMPLETED: SUCCESS PR #44: COMPLETED: SUCCESS PR #43: COMPLETED: SUCCESS # 3. Check for conflicts $ for pr in 45 44 43; do mergeable=$(gh pr view $pr --json mergeable -q .mergeable) echo "PR #$pr: $mergeable" done PR #45: MERGEABLE PR #44: MERGEABLE PR #43: MERGEABLE # 4. Auto-merge all $ for pr in 45 44 43; do gh pr merge $pr --auto --squash --delete-branch echo "✓ PR #$pr queued for auto-merge" done ✓ PR #45 queued for auto-merge ✓ PR #44 queued for auto-merge ✓ PR #43 queued for auto-merge # 5. Monitor merge progress $ watch -n 5 'gh pr list --author "app/dependabot" --json number,state,merged' # 6. Verify all merged $ gh pr list --author "app/dependabot" --state merged --limit 5 ✓ #45 Bump @types/node from 20.10.0 to 20.10.5 (merged 2m ago) ✓ #44 Bump @types/react from 18.2.0 to 18.2.4 (merged 3m ago) ✓ #43 Bump @types/jest from 29.5.0 to 29.5.1 (merged 4m ago) ``` ### Example 4: Comprehensive Repository Triage **Scenario**: Clean up accumulated technical debt ```bash # 1. Create triage issue $ gh issue create --title "Repository Maintenance - $(date +%Y-%m-%d)" --body " ## GitHub Maintenance Triage **Created**: $(date) **Status**: In Progress ### Failed Workflows $(gh run list --status failure --limit 10 --json name,conclusion,createdAt | \ jq -r '.[] | "- [ ] \(.name) - \(.conclusion) (\(.createdAt))"') ### Failed PRs $(gh pr list --search "status:failure" --json number,title | \ jq -r '.[] | "- [ ] #\(.number): \(.title)"') ### Dependabot Backlog $(gh pr list --author "app/dependabot" --json number,title | \ jq -r '.[] | "- [ ] #\(.number): \(.title)"') " Created issue #123 # 2. Prioritize issues # P0: Main branch CI failure (#1234567) # P1: Feature PR blocked (#87) # P2: 12 Dependabot PRs # 3. Fix P0: Main branch CI $ gh run view 1234567 --log-failed > failure.log $ cat failure.log | grep -A 5 "FAILED" # [Implement fix as in Example 1] $ gh issue comment 123 --body "✅ **P0 Fixed**: Main branch CI - Root cause: Test timeout - Fix: Increased timeout, optimized test setup - Verification: Run #1234580 passed" # 4. Fix P1: Feature PR $ gh pr checkout 87 $ gh pr checks 87 # [Implement fixes as in Example 2] $ gh issue comment 123 --body "✅ **P1 Fixed**: Feature PR #87 unblocked - Fixed linting issues - Resolved merge conflicts - All checks passing, ready for review" # 5. Handle P2: Dependabot backlog # [Batch process as in Example 3] $ gh issue comment 123 --body "✅ **P2 Progress**: Dependabot cleanup - Merged 8 patch updates (auto-merge) - Merged 3 minor updates after testing - Flagged 1 major update for manual review (#92)" # 6. Summary $ gh issue comment 123 --body "## Triage Complete **Summary**: - ✅ 1 critical CI failure resolved - ✅ 1 feature PR unblocked - ✅ 11/12 Dependabot PRs merged - ⏳ 1 major version upgrade awaiting review (#92) **Time saved**: ~3 hours of manual work **Next steps**: Review major version upgrade #92" $ gh issue close 123 ``` --- ## Error Handling ### Common Failure Modes #### 1. Authentication Failures **Error:** ``` gh: authentication failed ``` **Recovery:** ```bash # Check authentication status $ gh auth status # Re-authenticate $ gh auth login # Refresh token $ gh auth refresh ``` #### 2. Permission Denied **Error:** ``` Resource not accessible by personal access token ``` **Recovery:** ```bash # Check required scopes $ gh auth status # Token needs these scopes: # - repo (full control) # - workflow (update GitHub Actions) # - write:packages (if using container registry) # Re-authenticate with correct scopes $ gh auth refresh -h github.com -s repo,workflow ``` #### 3. Workflow Not Found **Error:** ``` could not find workflow run: 404 Not Found ``` **Recovery:** ```bash # List recent runs to find correct ID $ gh run list --limit 20 # Verify run ID exists $ gh api repos/{owner}/{repo}/actions/runs/{run-id} # If run too old, it may be archived - use workflow name $ gh workflow view "CI" --limit 50 ``` #### 4. Merge Conflicts **Error:** ``` merge conflict in <file> ``` **Recovery:** ```bash # Abort merge $ git merge --abort # Or resolve conflicts: $ git status # Edit conflicted files, remove markers $ git add <resolved-files> $ git commit # Or use --theirs for lock files $ git checkout --theirs package-lock.json $ npm install $ git add package-lock.json $ git commit ``` #### 5. Rate Limiting **Error:** ``` API rate limit exceeded ``` **Recovery:** ```bash # Check rate limit status $ gh api rate_limit # Wait for rate limit reset $ gh api rate_limit | jq .resources.core.reset # Or use authenticated requests (higher limit) $ gh auth login # Increases limit from 60/hr to 5000/hr ``` ### Recovery Strategies #### Strategy 1: Retry with Backoff ```bash # For transient failures retry_count=0 max_retries=3 while [ $retry_count -lt $max_retries ]; do if gh run rerun <run-id>; then echo "Success!" break else retry_count=$((retry_count + 1)) wait_time=$((2 ** retry_count)) echo "Retry $retry_count/$max_retries after ${wait_time}s..." sleep $wait_time fi done ``` #### Strategy 2: Fallback to API ```bash # If gh CLI fails, use direct API gh api repos/{owner}/{repo}/actions/runs/{run-id}/rerun \ -X POST \ --silent ``` #### Strategy 3: Graceful Degradation ```bash # If automated fix fails, document for manual intervention if ! make test; then gh pr comment <pr-number> --body "⚠️ Automated fix attempted but tests still failing. **Error:** \`\`\` $(make test 2>&1 | tail -20) \`\`\` Manual review required. See logs for details." exit 1 fi ``` ### When to Abort **Abort execution if:** - ❌ Exceeded maximum retry attempts (default: 3) - ❌ Detected circular dependency in fixes - ❌ Working directory becomes dirty unexpectedly - ❌ GitHub API returns 403 Forbidden (not just rate limit) - ❌ Would cause data loss (force-push to protected branch) - ❌ Cannot verify current state (git status fails) **Abort procedure:** ```bash # 1. Stop all operations # 2. Document state echo "ABORTED: $(date)" > abort-state.log git status >> abort-state.log gh run list --limit 5 >> abort-state.log # 3. Revert any partial changes git reset --hard HEAD git clean -fd # 4. Create issue with diagnostic info gh issue create --title "Automated maintenance aborted" \ --body "$(cat abort-state.log)" \ --label "automation-failure" # 5. Notify user echo "❌ Automation aborted. See issue for details." ``` --- ## Best Practices ### Before You Start 1. **Verify setup**: ```bash gh auth status git status make test # Ensure baseline works ``` 2. **Create tracking issue** for audit trail 3. **Understand repository conventions**: - Branch naming (feat/, fix/, chore/) - Commit message format - PR merge strategy (squash vs merge) ### During Execution 1. **Small, focused commits**: One fix per commit 2. **Descriptive messages**: Include run/PR numbers 3. **Test before push**: Run tests locally when possible 4. **Comment proactively**: Explain automated actions 5. **Monitor progress**: Use `gh run watch` and `gh pr checks` ### After Completion 1. **Verify all changes merged** 2. **Close tracking issues** 3. **Clean up branches**: Delete merged branches 4. **Document patterns**: Note recurring issues for prevention --- ## Skill Activation To use this skill, simply say: - "Fix failing GitHub Actions" - "Clean up Dependabot PRs" - "Resolve PR #123 check failures" - "Triage repository issues" Claude Code will then: 1. Assess the current state using `gh` commands 2. Prioritize issues by severity 3. Systematically fix issues following this skill's workflows 4. Document all actions taken 5. Verify resolutions 6. Provide summary report **Remember**: This skill automates mechanical tasks but escalates complex decisions to you. You stay in control while saving hours of manual work.