Create GitHub pull requests using the gh CLI. Use when the user wants to create a new PR, submit code for review, or open a pull request. Trigger keywords - create PR, pull request, new PR, submit for review, code review.
Create pull requests on GitHub using the gh CLI.
gh CLI must be authenticated (gh auth status)<issue-number>-<description>/<username>Run the local pre-commit task before opening a PR:
mise run pre-commit
Before creating a PR, verify:
You're not on main - Never create PRs directly from main:
# Should NOT be "main"
git branch --show-current
Branch follows naming convention - Format: <issue-number>-<description>/<initials>
# Example: 1234-add-pagination/jd
git branch --show-current
Consider squashing commits - For cleaner history, squash related commits before pushing:
# Squash last N commits into one
git reset --soft HEAD~N
git commit -m "feat(component): description"
Ensure your branch is pushed to the remote:
git push -u origin HEAD
Basic PR creation (opens editor for description):
gh pr create
With title and body:
gh pr create --title "PR title" --body "PR description"
PR titles must follow the conventional commit format:
<type>(<scope>): <description>
Types:
feat - New featurefix - Bug fixdocs - Documentation onlyrefactor - Code change that neither fixes a bug nor adds a featuretest - Adding or updating testschore - Maintenance tasks (CI, build, dependencies)perf - Performance improvementScope is typically the component name (e.g., evaluator, cli, sdk, jobs).
Examples:
feat(evaluator): add support for custom rubricsfix(jobs): handle timeout errors gracefullydocs(sdk): update authentication examplesrefactor(models): simplify deployment logicchore(ci): update Python version in pipelineEvery PR must have:
Every PR must be assigned to the user creating it. Use the --assignee flag:
gh pr create --title "Title" --assignee "@me"
Use Closes #<issue-number> in the body to auto-close the issue when merged:
gh pr create \
--title "Fix validation error for empty requests" \
--assignee "@me" \
--body "Closes #123
## Summary
- Added validation for empty request bodies
- Returns 400 instead of 500"
For work-in-progress that's not ready for review:
gh pr create --draft --title "WIP: New feature" --assignee "@me"
gh pr create --title "Title" --label "area:cli" --label "topic:security"
Default target is main. To target a different branch:
gh pr create --base "release-1.0"
PR descriptions must follow the project's PR template structure:
## Summary
<!-- 1-3 sentences: what this PR does and why -->
## Related Issue
<!-- Fixes #NNN or Closes #NNN -->
## Changes
<!-- Bullet list of key changes -->
## Testing
<!-- What testing was done? -->
- [ ] `mise run pre-commit` passes
- [ ] Unit tests added/updated
- [ ] E2E tests added/updated (if applicable)
## Checklist
- [ ] Follows Conventional Commits
- [ ] Commits are signed off (DCO)
- [ ] Architecture docs updated (if applicable)
Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.
gh pr create \
--title "feat(cli): add pagination to sandbox list" \
--assignee "@me" \
--body "$(cat <<'EOF'
## Summary
Add `--limit` and `--offset` flags to `openshell sandbox list` for pagination.
## Related Issue
Closes #456
## Changes
- Added `offset` and `limit` query parameters to the sandbox list API call
- Default limit is 20, max is 100
- Response includes `total_count` field
## Testing
- [x] `mise run pre-commit` passes
- [x] Unit tests added/updated
- [ ] E2E tests added/updated (if applicable)
## Checklist
- [x] Follows Conventional Commits
- [x] Commits are signed off (DCO)
- [ ] Architecture docs updated (if applicable)
EOF
)"
| Option | Description |
|---|---|
--title, -t | PR title (use conventional commit format) |
--body, -b | PR description |
--assignee, -a | Assign to user (use @me for yourself) |
--reviewer, -r | Request review from user |
--draft | Create as draft (WIP) |
--label, -l | Add label (can use multiple times) |
--base, -B | Target branch (default: main) |
--head, -H | Source branch (default: current) |
--web | Open in browser after creation |
The command outputs the PR URL and number.
Display the URL using markdown link syntax so it's easily clickable:
Created PR [#123](https://github.com/OWNER/REPO/pull/123)
If the user asks to wait for a green CI before posting the RFR, use this snippet to monitor the workflow run:
# Watch the latest workflow run for the current branch
gh run watch
Or poll manually:
RUN_ID=$(gh run list --branch "$(git branch --show-current)" --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID"