git-pr

git-pr — automatically open a PR/MR

The real effort is at both ends: before submitting, confirm it has been pushed to the remote; after submitting, always check CI and conflicts and provide a plan; the middle part, "open a PR," is itself just a one-line CLI call. All gh/glab platform differences are pushed down into references/; this file keeps only the fork pointers.

🔴 Hard rule (the only guardrail)

Do not push proactively. What to do instead: only before submitting a PR/MR git push -u origin <branch>(a necessary prerequisite for opening a PR, not an unauthorized push); at any other time or for any other branch, do not push; anything outside the push scope is left to the user's explicit instructions.

Workflow

1. Identify platform + target branch

git remote get-url origin

Remote host	Tool	How to choose the default target branch
`github.com` / GH Enterprise	`gh`	`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
`gitlab.*` / self-hosted GitLab	`glab`	`glab repo view` take the default branch
Other/unrecognizable	🔴 STOP	AskUserQuestion to ask the user for the platform and tool

Target branch priority: user --base <branch> parameter > repository default branch.
Tool missing (which gh/which glab empty) → report installation guidance, do not force-run.
⚠️ Self-hosted GitLab / GH Enterprise domain recognition,glab 's GITLAB_HOST configuration, RTK wrapper intercepting gh/glab output, and other pitfalls: for the single source of truth see references/platform-and-content.md §platform。

✅ Completion criteria: the platform has been determined to be one of GitHub/GitLab (or has STOPPED to ask the user), the corresponding tool gh/glab has been confirmed available,$BASE has been determined (user-provided parameter or the repository default branch has been obtained).

2. Generate PR/MR content

BASE=<目标分支>
git log --oneline "origin/$BASE...HEAD"     # 三点:本分支相对 merge-base 的提交(非双点)
git diff --stat "origin/$BASE...HEAD"        # 改动概览

How to write the title + structured body (changes/impact scope/verification), reuse of the repository PR template: for the single source of truth see references/platform-and-content.md §content。

✅ Completion criteria: the commit list and diff overview for the three-dot range have been obtained, and the title + structured body written from them is ready (or the repository's existing PR/MR template has been applied and the corresponding sections filled in).

3. Submit (create only, do not merge)

# GitHub
gh pr create --base "$BASE" --head "$(git branch --show-current)" --title "<标题>" --body "<正文>"
# GitLab
glab mr create --target-branch "$BASE" --title "<标题>" --description "<正文>"

After submission, stop at "created"—whether to merge and when to merge is left to the user to decide by pressing a button on the platform; this skill does not touch it. Return the CLI output's PR/MR URL(must be given to the user). For all command parameters (draft/reviewer/label, etc.) see references/platform-and-content.md §create。

✅ Completion criteria:gh pr create/glab mr create has successfully returned exit code 0 and the PR/MR URL has been returned to the user (or it has been determined that a PR/MR already exists for the same branch, in which case use the existing URL).

4. Check CI + conflicts → 🔴 CHECKPOINT

# GitHub
gh pr checks                                   # CI 状态
gh pr view --json mergeable,mergeStateStatus   # 冲突/可合并
# GitLab
glab ci status
glab mr view

Check result	Action
CI all green + mergeable	Report "PR/MR created, CI passed, no conflicts" + URL, done
CI action failed	Get a summary of the failed job logs, AskUserQuestion: do you want me to fix it? Include diagnosis + suggested plan
Merge conflicts present	AskUserQuestion: should the target branch be merged/rebased in to resolve the conflicts? (point to git-merge/git-rebase)
`mergeable=UNKNOWN`	GitHub is still computing in the background; wait a bit and recheck once before judging (do not treat as no conflicts), see references/ci-and-conflict.md §mergeable
CI still running	Report the current pending status, give a "recheck later `gh pr checks`/`glab ci status` " hint

For CI field meanings, how to obtain failure logs, and conflict determination details, see references/ci-and-conflict.md。

✅ Completion criteria: Each item has been judged one by one according to the table above and the corresponding action has been given; when CI fails or there is a conflict, AskUserQuestion has actually been issued to let the user decide (whether to fix/whether to resolve the conflict), without modifying code on one's own or merging on the user's behalf.

Failure handling (trigger condition → first-line fix → fallback if still failing)

Trigger condition	First-line fix	Fallback if still failing
`gh`/`glab` Not logged in	Prompt `gh auth login` / `glab auth login`(user runs it themselves in the terminal)	Do not retry when not logged in; STOP and wait for user authorization
PR/MR already exists (same branch)	Change to returning the existing PR/MR URL instead of creating it again	List existing PR statuses for the user to decide
Target branch does not exist	List remote branches, use AskUserQuestion to let the user choose the correct base	Use the default branch and clearly inform the user
CI fails but logs cannot be obtained	Provide the PR page URL so the user can view checks in the web page	Mark "CI failed, logs need to be checked in the web page" and do not guess the cause blindly

Honest boundaries

Only GitHub (gh)/GitLab (glab) are supported; Bitbucket/Gitea/other self-hosted platforms are not covered, and if they cannot be recognized, STOP.
Do not resolve the root cause of CI failures; only obtain a log summary + suggestions; whether to fix is decided by the user.
The quality of the PR body depends on the quality of the commits; if commits are scattered or messages are empty, the body can only be roughly written based on the diff.
Do not touch PR merging and do not modify branch protection rules.