Create GitHub Pull Request
Analyze code changes on the current branch and create a well-structured pull request using gh.
Workflow
1. Verify prerequisites
Check that you're in a git repo, on a feature branch (not main/master), gh is authenticated, and warn about uncommitted changes:
git rev-parse --is-inside-work-tree
git branch --show-current
gh auth status
git status --porcelainIf any check fails, report the specific error and stop. If git status --porcelain returns output, warn the user: "You have uncommitted changes — they won't be included in this PR." Then continue (don't stop).
2. Check for existing PRs
Before creating a new PR, check if one already exists for this branch:
gh pr list --head "$(git branch --show-current)" --state all --json number,title,state,url- If an open PR exists: report the existing PR URL and stop — do not create a duplicate.
- If a merged PR exists: proceed to create a new PR (the user has new changes to submit).
- If a closed (not merged) PR exists: proceed to create a new PR.
- If no PR exists: proceed normally.
3. Determine base branch
If a base branch was specified in the instructions (e.g. for stacked PRs), use that. Otherwise auto-detect: try main, then master, then the default branch from gh repo view --json defaultBranchRef.
4. Gather change context
Use the base branch determined above for all diffs:
git log --oneline <base>..HEAD
git diff <base>..HEAD --stat
git diff <base>..HEAD5. Categorize changes
Group the diff into:
- Features: new functionality
- Fixes: bug corrections with issue references
- Refactoring: code improvements without behavior changes
- Dependencies: package updates with version numbers
Note modified files, functions/classes affected, and import changes.
6. Generate PR content
Look for .github/PULL_REQUEST_TEMPLATE.md in the project root. If found, use it as the PR body template and fill in every section with actual content from the diff analysis. If no template exists, write a clear description covering what changed and why.
PR title format: [TICKET-ID]: brief description (max 80 chars). The ticket ID must be the very first element in the title. Extract the ticket ID from the branch name or commit messages. Example: [EC-1111]: Fix item license search query. Do NOT place conventional prefixes (feat:, fix:, etc.) before the ticket ID.
7. Create the PR
Write the PR body to a temp file to safely handle special characters, quotes, and newlines:
tmpfile=$(mktemp /tmp/pr-body.XXXXXX.md)
cat > "$tmpfile" << 'PRBODY'
<body content here>
PRBODY
gh pr create --title "<title>" --body-file "$tmpfile" --draft [--base "<base_branch>"]
rm -f "$tmpfile"If a base branch was specified in the instructions (e.g. for stacked PRs), use --base to target it instead of the default branch.
Then open it in the browser (suppress output — do not let gh pr view print anything to stdout):
gh pr view --web 2>/dev/null || true8. Report result
Return ONLY this JSON (no other text before or after):
{
"pr_url": "<full GitHub PR URL>",
"pr_number": <number>,
"title": "<PR title>",
"status": "success"
}On failure:
{
"pr_url": "",
"pr_number": 0,
"title": "",
"status": "failed",
"error_message": "<what went wrong>"
}Error handling
- No git repo: "Not in a git repository. Run from a project root."
- No changes: "No commits found ahead of the base branch."
- gh not installed/authed: "Install GitHub CLI and run
gh auth login." - Push rejected: push the branch first, then retry PR creation.