CreatePR Workflow

Create a GitHub pull request with validations, auto-push, and template support.

When to Use

• “create pr”
• “open pull request”
• “new pr”
• “submit changes”

Required: Use gh-pr create

Always use gh-pr create - it provides built-in validations and template support that ensure consistent PR quality.

# Basic usage - validates branch, pushes, then creates PR
gh-pr create

# With title and body
gh-pr create -t "feat: Add authentication" -b "Implements JWT auth"

# Create from main branch with a new branch name
gh-pr create --branch feat/my-feature

# With template and draft mode
gh-pr create --template feature.md --draft

# Require signed commits
gh-pr create --require-signed

# Skip pushing (if already pushed)
gh-pr create --no-push

# Force push (for amended commits)
gh-pr create --force

gh-pr create Features

Flag	Description
--branch	Create new branch before PR (useful from main)
--allow-main	Override main/master branch check
--no-push	Skip pushing to remote
--require-signed	Verify commits are GPG signed
--force, -f	Force push with lease
--template	Use specific PR template
--draft, -d	Create as draft PR
--reviewer, -r	Request reviewers
--assignee, -a	Assign users
--label, -l	Add labels
--web, -w	Open in browser

Built-in Validations

The tool automatically:

1. Validates branch: Prevents creating PRs from main/master
2. Checks uncommitted changes: Ensures clean working directory
3. Pushes to remote: Auto-pushes before creating PR
4. Detects remote: Uses personal fork remote if available
5. Loads templates: Discovers and uses PR templates

Fallback: Direct gh CLI (Exceptional Cases Only)

Only use gh pr create directly when gh-pr create cannot be used (e.g., untracked files blocking validation, cross-fork PRs to different upstream). In these cases, you must manually ensure:

• Not on main/master branch
• Branch is pushed to remote
• PR template is properly filled

# Cross-fork PR (gh-pr doesn't support --repo flag)
gh pr create \
  --repo upstream/repo \
  --base main \
  --head yourname:feature-branch \
  --title "feat: Add feature" \
  --body "$(cat .github/pull_request_template.md)"

Workflow Steps (Manual)

1. Pre-flight Checks

# Verify not on main/master
branch=$(git branch --show-current)
[[ "$branch" == "main" || "$branch" == "master" ]] && echo "Error: on protected branch"

# Check for uncommitted changes
git status --porcelain

# Check if PR already exists
gh pr status

2. Create Branch (if needed)

# From main, create feature branch
git checkout -b feat/my-feature

3. Push Branch

# Push with upstream tracking
git push -u origin $(git branch --show-current)

4. Create PR

# Use template if available
gh-pr create --template PULL_REQUEST_TEMPLATE.md

# Or basic creation
gh pr create --fill

Template Discovery

Templates are discovered from:

• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE/ (directory with multiple templates)
• docs/pull_request_template.md
• PULL_REQUEST_TEMPLATE.md

List available templates:

gh-pr list-templates

Common Scenarios

Quick PR from Feature Branch

# Already on feature branch with commits
gh-pr create -t "feat: Add user dashboard" --web

PR from Main (Create New Branch)

# On main with uncommitted changes
git checkout -b fix/typo
git add -A && git commit -m "fix: correct typo"
gh-pr create

Draft PR for Early Feedback

gh-pr create --draft -t "WIP: New feature"

Require Signed Commits

# Will fail if any commits are unsigned
gh-pr create --require-signed

PR Title Format

Follow conventional commits:

<type>: <description>

Types: feat, fix, docs, chore, refactor, test, perf, ci

Examples:

• feat: Add user authentication
• fix: Resolve memory leak in parser
• docs: Update API documentation
• refactor: Simplify error handling

Best Practices

1. Use gh-pr create: Built-in validations prevent common mistakes
2. Descriptive titles: Follow conventional commit format
3. Fill templates: Don’t leave sections empty
4. Link issues: Use “Closes #123” for auto-close
5. Add reviewers: Request appropriate reviewers
6. Use draft for WIP: Don’t request review for incomplete work
7. Check before creating: Ensure commits are ready
8. Sign commits: Enable commit signing for trusted contributions