github-issue-resolver

name	github-issue-resolver
description	Strategically resolves GitHub Actions failures, failed pull requests, and Dependabot issues using the gh CLI with intelligent analysis and automated fixes.

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

# 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

# View summary of failed run
gh run view <run-id>

# Get detailed logs for failed jobs only
gh run view <run-id> --log-failed

# Download all logs for offline analysis
gh run view <run-id> --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:

# 1. Identify files needing changes from error logs
# 2. Read relevant files
# 3. Make targeted fixes
# 4. Commit changes with descriptive message

git add <affected-files>
git commit -m "fix: resolve <specific-error> in <component>

Fixes GitHub Actions run #<run-id>
Root cause: <brief-explanation>
Changes: <list-of-changes>"

# 5. Push changes
git push origin <branch-name>

Step 5: Re-trigger and Verify

# Re-run failed jobs
gh run rerun <run-id> --failed

# Watch run progress
gh run watch <run-id>

# Verify success
gh run view <run-id>

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

# 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 <pr-number> --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

# Checkout PR branch locally
gh pr checkout <pr-number>

# View PR status and checks
gh pr checks <pr-number>

# View detailed check information
gh pr view <pr-number>

Step 3: Fix Check Failures

Common Scenarios:

Scenario A: Failed Tests

# 1. Identify failing tests from check output
gh pr checks <pr-number>

# 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 #<pr-number>"
git push

Scenario B: Merge Conflicts

# 1. Update branch with base
gh pr update-branch <pr-number>

# 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

# 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 #<pr-number>"
git push

Step 4: Document and Request Review

# Add comment explaining fixes
gh pr comment <pr-number> --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 <pr-number> --add-reviewer <username>

# Mark as ready for review (if draft)
gh pr ready <pr-number>

Step 5: Merge When Ready

# Check merge eligibility
gh pr view <pr-number> --json mergeable,mergeStateStatus

# Merge if all checks pass
gh pr merge <pr-number> --auto --squash  # or --merge, --rebase

# Verify merge
gh pr view <pr-number> --json state,merged

---

3. Dependabot Issue Handling

Objective: Efficiently manage automated dependency updates.

Step 1: Identify Dependabot PRs

# 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:

# 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 <pr-number> --json labels

# Check for breaking changes in release notes
gh pr view <pr-number> --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:

# 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:

# 1. Checkout Dependabot PR
gh pr checkout <pr-number>

# 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 <pr-number> --body "@dependabot rebase"

Step 5: Use Dependabot Commands

Dependabot Command Reference:

# Rebase PR to resolve conflicts
gh pr comment <pr-number> --body "@dependabot rebase"

# Recreate PR
gh pr comment <pr-number> --body "@dependabot recreate"

# Merge PR (if auto-merge enabled)
gh pr comment <pr-number> --body "@dependabot merge"

# Squash and merge
gh pr comment <pr-number> --body "@dependabot squash and merge"

# Ignore this dependency
gh pr comment <pr-number> --body "@dependabot ignore this dependency"

# Ignore this major version
gh pr comment <pr-number> --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:

# Enable auto-merge for Dependabot PRs with passing checks
gh pr merge <pr-number> --auto --squash

# Or merge immediately
gh pr merge <pr-number> --squash --delete-branch

# Batch merge multiple PRs
for pr in <pr-numbers>; 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

# 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

# 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 (#<run-id>)
- [ ] Merge security patch (#<pr-number>)

**P1 Issues:**
- [ ] Fix feature PR #<number>
- [ ] 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:

# After each fix, update tracking issue
gh issue comment <tracking-issue-number> --body "✅ Completed: Fixed main branch CI
- Root cause: Test timeout in integration suite
- Fix: Increased timeout from 5m to 10m
- Verification: Run #<new-run-id> passed"

Phase 5: Summary Report

# After session, create summary
gh issue comment <tracking-issue-number> --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

# View repository details
gh repo view

# Clone repository
gh repo clone <owner>/<repo>

# Fork repository
gh repo fork <owner>/<repo>

Workflow Runs

# List runs
gh run list [--workflow <name>] [--status <status>] [--limit <n>]

# View run details
gh run view <run-id> [--log] [--log-failed]

# Rerun workflows
gh run rerun <run-id> [--failed]  # Rerun only failed jobs
gh run rerun <run-id>             # Rerun all jobs

# Watch run progress
gh run watch <run-id>

# Download run artifacts
gh run download <run-id>

# Cancel run
gh run cancel <run-id>

Pull Requests

# List PRs
gh pr list [--author <user>] [--label <label>] [--search <query>]

# View PR details
gh pr view <pr-number> [--json <fields>]

# Create PR
gh pr create --title "<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

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# If gh CLI fails, use direct API
gh api repos/{owner}/{repo}/actions/runs/{run-id}/rerun \
  -X POST \
  --silent

Strategy 3: Graceful Degradation

# 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:

# 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:

   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.