How to Create a Pull Request Using GitHub CLI

Prerequisites

gh

1. Install GitHub CLI if you haven't already:
   bash

   # 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

2. Authenticate with GitHub:
   bash

   gh auth login

Pre-flight Checks

1. Run

   git status

   to check for uncommitted changes (staged, unstaged, or untracked files)
2. If uncommitted changes exist, use the Skill tool to run the

   commit

   skill first:

   Skill: commit

3. This ensures all your work is committed before creating the PR

Creating a New Pull Request

1. First, prepare your PR description following the template in @.github/pull_request_template.md
2. Use the

   gh pr create --draft

   command to create a new pull request:
   bash

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

   For more complex PR descriptions with proper formatting, use the

   --body-file

   option with the exact PR template structure:
   bash

   # Create PR with proper template structure
   gh pr create --draft --title "✨(scope): Your descriptive title" --body-file .github/pull_request_template.md --base main

Best Practices

1. Language: Always use English for PR titles and descriptions
2. 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

3. Description Template: Always use our PR template structure from @.github/pull_request_template.md:
4. 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
5. 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

1. Using Non-English Text: All PR content must be in English
2. Incorrect Section Headers: Always use the exact section headers from the template
3. Adding Custom Sections: Stick to the sections defined in the template
4. Using Outdated Templates: Always refer to the current @.github/pull_request_template.md file

Missing Sections

Additional GitHub CLI PR Commands

# 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

1. Create a file named

   pr-template.md

   with your PR template
2. Use it when creating PRs:

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

Related Documentation

• PR Template
• Conventional Commits
• GitHub CLI documentation