Github Pr Via Gh Cli

Opening a GitHub PR via gh

When to use

The user says "open a PR" / "send a pull request" and gh is available (which gh succeeds). Works equally for first-party repos and forks.

Problem

Getting all of these right on the first try:

• Do I need to fork, or can I push a branch directly?
• What's the base branch (main vs master)?
• Body with multiple paragraphs, backticks, and lists — how to pass?

Solution

1. Determine push access and the fork question.

``bash gh auth status # who am I? git -C remote -v # what does origin point to? ``

• If origin is owned by the authenticated user → push directly

to a branch, no fork needed.

• Otherwise → fork first: gh repo fork --remote=true.

1. Create a descriptive branch, commit, push.

``bash git -C checkout -b git -C add git -C commit -F .commit_msg.tmp # see related skill git -C push -u origin ``

1. Check the default branch, don't assume main:

``bash git -C symbolic-ref refs/remotes/origin/HEAD | sed 's@^.*/@@' ``

1. Create the PR with a body file (see related skill):

``bash gh pr create \ --repo / \ --base \ --head \ --title "" \ --body-file pr_body.md ``

gh prints the PR URL on success. Capture it.

Example

gh pr create --repo chen3feng/cn-doc-style-guide \
  --base master --head add-md-style-tools \
  --title 'Add Python tools for checking and auto-fixing Chinese Markdown docs' \
  --body-file pr_body.md
# → https://github.com/chen3feng/cn-doc-style-guide/pull/1

Pitfalls

• Anti-pattern — never do this:

``bash gh pr create --body "$(cat / cmdand quote> — the agent sees "command interrupted" and the PR is never filed. Always write the body to a file via the editor tool and pass --body-file . See [shell-heredoc-and-multiline-strings](../shell-heredoc-and-multiline-strings/SKILL.md).

• --title with backticks or $ through the shell is still fragile;

prefer --body-file and keep the title short enough to put in a single-quoted string.

• --body "…\n…" does NOT give you line breaks. gh takes the

value verbatim; \n stays as a two-character literal and the PR body on GitHub will show \n in the middle of sentences. Always use --body-file for anything longer than one line (see [shell-heredoc-and-multiline-strings](../shell-heredoc-and-multiline-strings/SKILL.md)).

• Very long gh pr create invocations get backgrounded by some

agent shells — the command appears to "hang" and the PR URL never comes back. Keep the command short (use --body-file instead of a giant inline --body), and verify with gh pr list --repo / --state open afterwards.

• If you already created the PR and the body is malformed (e.g.

literal \n showing up), fix it without a new PR:

``bash gh pr edit --repo / --body-file pr_body.md ``

• If gh pr create complains about "no commits between base and head",

you forgot to push the branch first, or you branched off the wrong base — see [rebase-on-fresh-base-after-merge](../rebase-on-fresh-base-after-merge/SKILL.md).

• If the target repo has branch protection or required checks, the

command still succeeds — the PR is created but will sit in a pending state. Mention this to the user if relevant.

• **gh pr view --json mergeable,mergeStateStatus can return

"UNKNOWN" / "UNKNOWN" right after another PR lands on the same base.** GitHub computes mergeability asynchronously; the value is not populated instantly. If you need a decision (e.g. "does this PR still merge cleanly after the one we just merged?"), wait a few seconds and re-query:

``bash gh pr view --json mergeable,mergeStateStatus # → {"mergeable":"UNKNOWN","mergeStateStatus":"UNKNOWN"} sleep 5 gh pr view --json mergeable,mergeStateStatus # → {"mergeable":"MERGEABLE","mergeStateStatus":"CLEAN"} ``

Don't interpret a single UNKNOWN as "there's a conflict" — it just means GitHub hasn't finished the background check yet. The gh pr checks and the web UI exhibit the same delay.

• **gh run rerun --job wants the display name upstream, not

the YAML job key. When you select a specific workflow job to rerun (or view), --job takes the job's numeric databaseId and that ID is resolved against the display name** shown in the GitHub Checks UI — which is the name: field from the workflow YAML, not the jobs. identifier above it. Pattern-matching the YAML key will silently miss:

``yaml # .github/workflows/python-package.yml jobs: e2e-smoke: # ← YAML key name: E2E smoke (blade-test) # ← display name (what gh sees) ``

```bash # WRONG — filters on the YAML key, returns empty list, rerun fails. JOBID=$(gh run view --json jobs \ | jq -r '.jobs[] | select(.name=="e2e-smoke") | .databaseId') gh run rerun --job "$JOBID" # → IndexError / "Flags: ... -j, --job string ..."

# RIGHT — list jobs first, copy the actual display name. gh run view --json jobs \ | jq -r '.jobs[] | "\(.databaseId) \(.name) \(.conclusion)"' # 73167567958 E2E smoke (blade-test) success gh run rerun --job 73167567958 ```

The same applies to gh run view --log --job when you want to grep a specific job's log. Always list .jobs[].name first and copy the exact string; never assume it equals the YAML key.

See also

• [git-commit-author-identity](../git-commit-author-identity/SKILL.md)
• [shell-heredoc-and-multiline-strings](../shell-heredoc-and-multiline-strings/SKILL.md)
• [rebase-on-fresh-base-after-merge](../rebase-on-fresh-base-after-merge/SKILL.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chen3feng
• Source: chen3feng/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.