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 - For issue-backed work, the branch should follow `<issue-number>-<description>/<username>`. Exempt issue-less changes may use `<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/how-it-works/gateways/configuration.mdx` is updated in the same branch. If the change affects user-facing compute-driver setup, also update `docs/how-it-works/sandboxes/runtimes.mdx` or the relevant deployment docs. ### Check Agent Infrastructure Use the `sync-agent-infra` skill's maintenance map to identify related skill updates when the branch changes behavior, commands, or development workflows. Run its full consistency check when the branch adds, removes, or renames skills or crates; changes workflow relationships or skill coverage; modifies issue or PR templates; or changes agent cross-references. Resolve any drift before creating the PR. ### Run Pre-commit Checks Run the local pre-commit task before opening a PR: ```bash mise run pre-commit ``` ### Verify Branch State Before creating a PR, verify: 1. **You're not on main** - Never create PRs directly from main: ```bash # Should NOT be "main" git branch --show-current ``` 2. **Branch follows naming convention** - Use `<issue-number>-<description>/<initials>` for issue-backed work or `<description>/<initials>` for an exempt issue-less change. ```bash # Example: 1234-add-pagination/jd git branch --show-current ``` 3. **Consider squashing commits** - For cleaner history, squash related commits before pushing: ```bash # 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: ```bash git push -u origin HEAD ``` ## Creating a PR Basic PR creation (opens editor for description): ```bash gh pr create ``` With title and body: ```bash 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 Features, user-visible behavior changes, public API changes, architecture changes, and multi-PR efforts must link an accepted issue. Use `Closes #<issue-number>` in the body to auto-close the issue when merged: ```bash 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" ``` Small documentation fixes, mechanical maintenance, and obvious localized bug fixes may omit a separate issue when the PR contains enough context to review the decision and implementation together. In that case, write `No issue required: <brief reason>` in the Related Issue section. Do not use this exception for security fixes; follow `SECURITY.md`. ### Create as Draft For work-in-progress that's not ready for review: ```bash gh pr create --draft --title "WIP: New feature" ``` ### With Labels ```bash gh pr create --title "Title" --label "area:cli" --label "topic:security" ``` ### Target a Different Branch Default target is `main`. To target a different branch: ```bash gh pr create --base "release-1.0" ``` ## PR Description Format PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEMPLATE.md) structure: ```markdown ## Summary <!-- 1-3 sentences: what this PR does and why --> ## Related Issue <!-- Fixes #NNN / Closes #NNN, or "No issue required: <reason>" for an exempt change --> ## 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) ```bash gh pr create \ --title "feat(cli): add pagination to sandbox list" \ --body "$(cat <<'EOF' ## Summary Add `--page-size` and `--page-token` flags to `openshell sandbox list` for continuation-token pagination. ## Related Issue Closes #456 ## Changes - Added `page_size` and `page_token` fields to the sandbox list API call - Default page size is 100, max is 1,000 - Structured responses include `next_page_token` ## 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 | Option | Description | | ------------------- | ------------------------------------------ | | `--title, -t` | PR title (use conventional commit format) | | `--body, -b` | PR description | | `--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 | ## 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: ```bash # Watch the latest workflow run for the current branch gh run watch ``` Or poll manually: ```bash RUN_ID=$(gh run list --branch "$(git branch --show-current)" --limit 1 --json databaseId --jq '.[0].databaseId') gh run watch "$RUN_ID" ```