create-pr

name	create-pr
description	Create a GitHub pull request from the current branch. Use when: you have commits ready on a feature branch and need to open a PR, submit code for review, or propose changes to the main branch.
argument-hint	Optional PR title (e.g., "fix: resolve login issue")
user-invocable	true

Create Pull Request

When to Use

• You have a feature branch with commits that are ready for review
• You want to submit code changes to the main branch
• You need to create a PR through the CLI instead of the GitHub web interface
• Your branch is already pushed to origin

Prerequisites

• Git repository with a feature branch checked out
• Changes committed and pushed to remote
• GitHub CLI (gh) installed and authenticated (gh auth login)

Procedure

1. Verify Current Branch

Check that you're on the correct feature branch:

git status

Expected output: On branch <feature-branch>

2. Ensure Changes Are Pushed

Push your commits to the remote if not already done:

git push origin <branch-name>

3. Authenticate with GitHub CLI

If not already authenticated, run:

gh auth login

Follow the prompts:

• Select GitHub.com
• Choose HTTPS for protocol
• Answer Yes to authenticate Git
• Select Login with a web browser
• Copy the device code (e.g., DDBE-402E)
• Open the link and enter the code to complete authentication

4. Create the Pull Request

Run the create PR command:

gh pr create --head <branch-name>

Or use the shorthand if on the branch already:

gh pr create

5. Fill in PR Details

The CLI will prompt you for:

• Title (required): A clear description of the changes
  • Use conventional commits format when possible: feat:, fix:, docs:, etc.
  • Example: feat: remove file limit and add copy button
• Body (optional): Detailed description of what changed and why
  • Press e to open your default editor for longer descriptions
  • Press Enter to skip if you'll add details later
• Submit options:
  • Submit: Create the PR immediately
  • Submit as draft: Create as a draft PR (reviewer can request changes)
  • Continue in browser: Open GitHub to make additional changes
  • Add metadata: Configure labels, assignees, reviewers

Examples

Simple PR with CLI defaults

gh pr create --head files-limit

Then follow the prompts for title and description.

PR with explicit title and body

gh pr create --head feature-branch --title "fix: resolve login issue" --body "Fixes session validation bug"

Draft PR

gh pr create --head feature-branch --draft

Troubleshooting

Issue	Solution
gh: command not found	Install GitHub CLI: choco install gh (Windows) or brew install gh (macOS)
authentication required	Run gh auth login and complete the device code flow
branch not found on remote	Push with git push origin <branch-name> first
PR already exists	Check GitHub for an existing PR from this branch

Related Commands

• View pull requests: gh pr list
• View a specific PR: gh pr view <pr-number>
• Check PR status: gh pr status
• Close a PR: gh pr close <pr-number>