create-github-pr

Create GitHub Pull Request

Create pull requests on GitHub using the gh CLI.

Prerequisites

• The gh CLI must be authenticated (gh auth status)
• You must have commits on a branch that's pushed to the remote
• Branch should follow naming convention: <issue-number>-<description>/<username>

Before Creating a PR

Check Config Documentation

If the branch changes gateway TOML parsing, [openshell.gateway] fields, [openshell.drivers.<name>] fields, driver config defaults, or Helm rendering of gateway.toml, verify that docs/reference/gateway-config.mdx is updated in the same branch. If the change affects user-facing compute-driver setup, also update docs/reference/sandbox-compute-drivers.mdx or the relevant deployment docs.

Run Pre-commit Checks

Run the local pre-commit task before opening a PR:

mise run pre-commit

Verify Branch State

Before creating a PR, verify:

1. You're not on main - Never create PRs directly from main:

   # Should NOT be "main"
   git branch --show-current
   

2. Branch follows naming convention - Format: <issue-number>-<description>/<initials>

   # Example: 1234-add-pagination/jd
   git branch --show-current
   

3. 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"
   

Push Your Branch

Ensure your branch is pushed to the remote:

git push -u origin HEAD

Creating a PR

Basic PR creation (opens editor for description):

gh pr create

With title and body:

gh pr create --title "PR title" --body "PR description"

PR Title Format

PR titles must follow the conventional commit format:

<type>(<scope>): <description>

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• chore - Maintenance tasks (CI, build, dependencies)
• perf - Performance improvement

Scope is typically the component name (e.g., evaluator, cli, sdk, jobs).

Examples:

• feat(evaluator): add support for custom rubrics
• fix(jobs): handle timeout errors gracefully
• docs(sdk): update authentication examples
• refactor(models): simplify deployment logic
• chore(ci): update Python version in pipeline

Link to an Issue

Use Closes #<issue-number> in the body to auto-close the issue when merged:

gh pr create \
  --title "Fix validation error for empty requests" \
  --body "Closes #123

## Summary
- Added validation for empty request bodies
- Returns 400 instead of 500"

Create as Draft

For work-in-progress that's not ready for review:

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

With Labels

gh pr create --title "Title" --label "area:cli" --label "topic:security"

Target a Different Branch

Default target is main. To target a different branch:

gh pr create --base "release-1.0"

PR Description Format

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)

Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.

Example PR (Complete)

gh pr create \
  --title "feat(cli): add pagination to sandbox list" \
  --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)
EOF
)"

Useful Options

After Creating

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)

Monitor Workflow Run (Optional)

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"