github-pr

name	github-pr
description	Automate GitHub PR workflow: fork repo, analyze issues, create fix branches, submit PRs and handle CI failures

GitHub PR Automation Skill

Automates the complete GitHub Pull Request workflow from forking a repository to handling CI failures.

When to use this skill

Use this skill when you need to:

• Contribute bug fixes to open source projects
• Systematically analyze and fix issues in a GitHub repository
• Automate the PR creation and CI monitoring workflow
• Track fix progress across multiple issues

Prerequisites

Before using this skill, ensure:

• gh CLI is installed and authenticated (see Auto Setup below)
• git is configured with your user name and email
• You have appropriate permissions to fork repositories
• You understand the target repository's contribution guidelines

Auto Setup GitHub CLI

This skill includes an automatic setup script for GitHub CLI:

# Check if gh is installed and authenticated
./scripts/setup-gh.sh --check-only

# Full setup (install + auth + completion)
./scripts/setup-gh.sh

# Install without authentication
./scripts/setup-gh.sh --no-auth

The script will:

• ✅ Detect your operating system (Linux/macOS/Windows)
• ✅ Install gh using the appropriate package manager
• ✅ Set up shell completion (bash/zsh/fish)
• ✅ Guide you through authentication

Supported package managers:

• macOS: Homebrew
• Ubuntu/Debian: apt
• Fedora/CentOS/RHEL: dnf/yum
• Arch Linux: pacman
• Windows: winget/scoop/chocolatey

If automatic installation fails, see manual installation guide.

Workflow

Phase 1: Repository Preparation

1. Fork Target Repository

gh repo fork OWNER/REPO --clone=false

2. Clone Repository Locally

git clone https://github.com/YOUR_USERNAME/REPO.git
cd REPO
git remote add upstream https://github.com/OWNER/REPO.git

3. Scan and Analyze Issues

Analyze all open issues in the repository and create a structured analysis:

For each issue, determine:

• Issue number and title
• Creation date
• Problem description
• Affected files (estimate based on issue description)
• Fix feasibility: ✅ Can fix / ⚠️ Can fix with risks / ❌ Cannot fix
• Difficulty level: ⭐ Simple / ⭐⭐ Medium / ⭐⭐⭐ Hard
• Fix approach (brief explanation)

Output format (Markdown table):

| # | Issue | Title | Description | Affected Files | Difficulty | Feasibility | Fix Approach |
|---|-------|-------|-------------|----------------|------------|-------------|--------------|
| 1 | [#123](link) | **Title** | Brief desc | `file.go` | ⭐ Simple | ✅ Can fix | Explanation |

4. Create Fix Plan Branch

git checkout -b fix-plan

Create FIX_PLAN.md with the analysis table, then:

git add FIX_PLAN.md
git commit -m "docs: create fix plan for open issues"
git push origin fix-plan

Phase 2: Create Pull Request

1. Select Issue to Fix

Choose an issue from the FIX_PLAN.md based on:

• Feasibility (prioritize ✅)
• Difficulty (start with ⭐ Simple)
• Impact (user-facing issues first)

2. Create Fix Branch

git checkout master  # or main
git pull upstream master
git checkout -b fix/ISSUE_NUMBER-short-description

Branch naming convention:

• fix/123-client-ip-parsing (for bug fixes)
• feat/123-add-feature (for features)
• docs/123-update-readme (for documentation)

3. Implement Fix

Best practices:

• Read related code carefully before making changes
• Keep changes minimal and focused
• Follow the project's coding style
• Add or update tests to cover the fix
• Update documentation if needed

Common fix patterns:

• Input validation: Add checks for edge cases
• Error handling: Improve error messages and handling
• Type safety: Add type assertions or conversions
• Compatibility: Handle different input formats

4. Local Testing

Run the project's test suite:

# Common patterns
go test ./...                    # Go projects
npm test                         # Node.js projects
pytest                           # Python projects
cargo test                       # Rust projects

Verify:

• All existing tests pass
• New tests cover the fix
• Manual testing for edge cases
• No linter errors

5. Commit Changes

git add <changed_files>
git commit -m "fix: <concise description> (#ISSUE_NUMBER)

<Detailed explanation of what changed and why>

Fixes #ISSUE_NUMBER"

Commit message format:

• First line: type: subject (#issue) (50 chars max)
• Types: fix, feat, docs, test, refactor, style, chore
• Body: Detailed explanation (wrap at 72 chars)
• Footer: Fixes #123 or Closes #123

6. Push Branch

git push -u origin fix/ISSUE_NUMBER-short-description

7. Confirm PR Submission

Ask user for confirmation:

Ready to create PR for issue #123?
Title: fix: <description>
Base: OWNER/REPO:master
Head: YOUR_USERNAME/REPO:fix/123-description

Proceed? (yes/no)

8. Create Pull Request

gh pr create \
  --repo OWNER/REPO \
  --base master \
  --head YOUR_USERNAME:fix/ISSUE_NUMBER-description \
  --title "fix: <description> (#ISSUE_NUMBER)" \
  --body "$(cat <<EOF
## Description

Fixes #ISSUE_NUMBER

<Detailed explanation of the fix>

## Changes

- Change 1
- Change 2
- Change 3

## Testing

- [x] Added/updated tests
- [x] All tests pass locally
- [x] Linter passes

## Related Issues

Closes #ISSUE_NUMBER
EOF
)"

9. Monitor CI Checks

Fetch PR URL and monitor checks:

PR_URL=$(gh pr view --json url -q .url)
echo "PR created: $PR_URL"

# Check CI status
gh pr checks

If CI fails:

• Navigate to the PR page
• Click on failed check for details
• Identify the failure type:
  • Lint errors: Fix code style issues
  • Test failures: Fix broken tests
  • Build errors: Fix compilation issues
  • Coverage drop: Add more tests

10. Fix CI Failures

Loop until all checks pass:

1. Identify failure cause

   gh pr checks  # View all check statuses
   gh pr view    # View PR details and comments
   

2. Fix locally

   • Address the specific error
   • Run tests locally to verify
   • Run linter if applicable

3. Commit and push fix

   git add <files>
   git commit -m "fix: resolve CI error - <description>"
   git push
   

4. Wait and verify

   • CI will automatically re-run
   • Monitor status with gh pr checks
   • Repeat if new failures appear

11. Update Fix Plan

Once PR is created and CI passes:

git checkout fix-plan

Update FIX_PLAN.md to add PR status column:

| # | Issue | ... | PR Status |
|---|-------|-----|-----------|
| 1 | [#123](link) | ... | 🔄 MR中 [PR #456](pr_link) |

Status indicators:

• 🔄 MR中 (In Review)
• ✅ 已合并 (Merged)
• ❌ 已关闭 (Closed)
• ⏸️ 暂停 (On Hold)

git add FIX_PLAN.md
git commit -m "docs: update FIX_PLAN.md with PR #456 for issue #123"
git push origin fix-plan

12. Wait for Review

• Respond to reviewer comments promptly
• Make requested changes if needed
• Be patient and respectful
• Once approved, maintainer will merge

Examples

Example 1: Fixing Input Validation Bug

# 1. Select issue #4572 from FIX_PLAN.md
# 2. Create fix branch
git checkout master && git pull upstream master
git checkout -b fix/4572-client-ip-parsing

# 3. Implement fix in context.go
# 4. Add tests in context_test.go
# 5. Run tests
go test ./...

# 6. Commit
git add context.go context_test.go
git commit -m "fix: support non-standard X-Forwarded-For formats (#4572)"

# 7. Push and create PR
git push -u origin fix/4572-client-ip-parsing
gh pr create --repo gin-gonic/gin --base master \
  --title "fix: support non-standard X-Forwarded-For formats (#4572)" \
  --fill

# 8. Monitor CI
gh pr checks

Example 2: Handling CI Lint Errors

# CI failed with errcheck errors
# Fix by adding error handling
git add -u
git commit -m "fix: resolve errcheck lint errors"
git push

# Verify fix
gh pr checks

Common Issues and Solutions

Issue: Fork already exists

Solution: Use existing fork or delete and re-fork:

gh repo delete YOUR_USERNAME/REPO --yes
gh repo fork OWNER/REPO --clone=true

Issue: Merge conflicts

Solution: Rebase on upstream:

git fetch upstream
git rebase upstream/master
git push --force-with-lease

Issue: CI checks timeout

Solution: Wait and check if re-run is needed:

gh run list --repo OWNER/REPO
gh run rerun RUN_ID

Issue: Coverage decreased

Solution: Add more test cases to cover new code paths

Issue: Multiple lint errors

Solution: Run linter locally and fix all at once:

golangci-lint run                    # Go
npm run lint -- --fix                # JavaScript
flake8 . && black .                  # Python
cargo clippy -- -D warnings          # Rust

Best Practices

1. One issue per PR - Keep PRs focused and reviewable
2. Test thoroughly - Run full test suite before pushing
3. Follow conventions - Match project's style and patterns
4. Communicate clearly - Write descriptive commits and PR descriptions
5. Be responsive - Address review comments quickly
6. Stay updated - Regularly sync with upstream
7. Document changes - Update docs and comments
8. Handle failures promptly - Fix CI issues immediately

Commands Reference

Manual gh Installation

If the automatic setup script doesn't work, install gh manually:

macOS

brew install gh

Ubuntu/Debian

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | \
  sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | \
  sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install gh -y

Fedora/CentOS/RHEL

sudo dnf install gh

Windows

winget install --id GitHub.cli
# or use scoop
scoop install gh

Then authenticate:

gh auth login

GitHub CLI

gh auth login                         # Authenticate
gh auth status                        # Check auth status
gh repo fork OWNER/REPO              # Fork repository
gh pr create --fill                  # Create PR with auto-fill
gh pr checks                         # View CI status
gh pr view                           # View PR details
gh pr list --state open              # List open PRs
gh issue list --label bug            # List issues by label

Git

git remote -v                        # List remotes
git fetch upstream                   # Fetch upstream changes
git rebase upstream/master           # Rebase on upstream
git push --force-with-lease          # Safe force push
git log --oneline -10                # View recent commits

Notes

• Always sync with upstream before creating new branches
• Keep PRs small - Easier to review and merge
• Be patient - Reviews may take time
• Learn from feedback - Use reviews to improve
• Check CONTRIBUTING.md - Follow project guidelines
• Test edge cases - Think about unusual inputs
• Update FIX_PLAN.md - Track all PR progress
• Respect maintainers - They're volunteers too

Related Resources

• GitHub CLI Documentation
• Contributing to Open Source
• Writing Good Commit Messages
• Code Review Best Practices