How to Create a Pull Request Using GitHub CLI

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

Important: All PR titles and descriptions should be written in English.

Prerequisites

Check if gh is installed, if not follow this instruction to install it:

-

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

2. Authenticate with GitHub:

gh auth login

## Pre-flight Checks

Before creating a PR, check for uncommitted changes:

- Run `git status` to check for uncommitted changes (staged, unstaged, or untracked files)

- If uncommitted changes exist, use the Skill tool to run the `git:commit` command first:

Skill: git:commit

- This ensures all your work is committed before creating the PR

## Creating a New Pull Request

-

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

-

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

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:

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

-

**Language**: Always use English for PR titles and descriptions

-

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

-

**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

- **Using Non-English Text**: All PR content must be in English

- **Incorrect Section Headers**: Always use the exact section headers from the template

- **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 --draft --title "feat(scope): Your title" --body-file pr-template.md --base main