How to Create a Pull Request Using GitHub CLI

This guide explains how to create pull requests using GitHub CLI in our project.

Prerequisites

Install GitHub CLI if you haven't already:

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux
# Follow instructions at https://github.com/cli/cli/blob/trunk/docs/install_linux.md

Authenticate with GitHub:
```
gh auth login
```

Creating a New Pull Request

First, prepare your PR description following the template in .github/pull_request_template.md

Use the gh pr create command to create a new pull request:

# Basic command structure
gh pr create --title "✨(scope): Your descriptive title" --body "Your PR description" --base main --draft

For more complex PR descriptions with proper formatting, use the --body-file option with the exact PR template structure:

# Create PR with proper template structure
gh pr create --title "✨(scope): Your descriptive title" --body-file <(echo -e "## Issue\n\n- resolve:\n\n## Why is this change needed?\nYour description here.\n\n## What would you like reviewers to focus on?\n- Point 1\n- Point 2\n\n## Testing Verification\nHow you tested these changes.\n\n## What was done\npr_agent:summary\n\n## Detailed Changes\npr_agent:walkthrough\n\n## Additional Notes\nAny additional notes.") --base main --draft

Best Practices

PR Title Format: Use conventional commit format with emojis
- Always include an appropriate emoji at the beginning of the title
- Use the actual emoji character (not the code representation like :sparkles:)
- Examples:
  - ✨(supabase): Add staging remote configuration
  - 🐛(auth): Fix login redirect issue
  - 📝(readme): Update installation instructions
Description Template: Always use our PR template structure from .github/pull_request_template.md:
- Issue reference
- Why the change is needed
- Review focus points
- Testing verification
- PR-Agent sections (keep pr_agent:summary and pr_agent:walkthrough tags intact)
- Additional notes
Template Accuracy: Ensure your PR description precisely follows the template structure:
- Don't modify or rename the PR-Agent sections (pr_agent:summary and pr_agent:walkthrough)
- Keep all section headers exactly as they appear in the template
- Don't add custom sections that aren't in the template
Draft PRs: Start as draft when the work is in progress
- Use --draft flag in the command
- Convert to ready for review when complete using gh pr ready

Common Mistakes to Avoid

Incorrect Section Headers: Always use the exact section headers from the template
Modifying PR-Agent Sections: Don't remove or modify the pr_agent:summary and pr_agent:walkthrough placeholders
Adding Custom Sections: Stick to the sections defined in the template
Using Outdated Templates: Always refer to the current .github/pull_request_template.md file

Missing Sections

Always include all template sections, even if some are marked as "N/A" or "None"

Additional GitHub CLI PR Commands

Here are some additional useful GitHub CLI commands for managing PRs:

# List your open pull requests
gh pr list --author "@me"

# Check PR status
gh pr status

# View a specific PR
gh pr view <PR-NUMBER>

# Check out a PR branch locally
gh pr checkout <PR-NUMBER>

# Convert a draft PR to ready for review
gh pr ready <PR-NUMBER>

# Add reviewers to a PR
gh pr edit <PR-NUMBER> --add-reviewer username1,username2

# Merge a PR
gh pr merge <PR-NUMBER> --squash

Using Templates for PR Creation

To simplify PR creation with consistent descriptions, you can create a template file:

Create a file named pr-template.md with your PR template
Use it when creating PRs:

gh pr create --title "feat(scope): Your title" --body-file pr-template.md --base main --draft

4.1 KiB Executable File Raw Permalink Blame History