Remotes, pushing, and pull requests
Topology
Classify each remote using the facts repo-context.sh reports for it: owner, fork_of, permission, and the authenticated viewer. Never trust remote names alone.
| Situation | Push remote | PR target |
|---|---|---|
| One remote is the viewer's fork, and another remote points at that fork's parent | the fork | the parent |
| The viewer's fork exists, but no remote points at its parent | the fork | fork_of. Mention that the parent remote is missing. |
| The only remote is a repo the viewer owns, not a fork | that remote | the same repo, as a branch PR |
| The only remote is owned by someone else (org or company), and the viewer has no fork remote | stop | Explain the situation. Offer to fork with gh repo fork --remote --remote-name fork (needs approval), or to push to that repo directly, but only if the user explicitly asks. |
Names are swapped (for example origin is the company repo and upstream is the fork) |
the fork, whatever it is named | its parent. State the mismatch in the approval gate. |
Several remotes look like the viewer's fork, the fork's parent doesn't match the target, or ownership can't be determined (for example gh is unavailable) |
stop | Describe what you found and ask which remote is theirs. |
An org fork the viewer controls counts as theirs only if the user confirms it.
When the branch already tracks a remote (upstream: in the context output) and that remote passes these rules, keep using it.
Base branch
Pick the first of these that applies:
- The user named a base.
- The base of an open PR for this branch.
- A base that the contribution guide names (for example "target
develop"). - The target repository's default branch.
Before pushing, compare the branch against the target base:
git fetch <target-remote> <base>
git rev-list --left-right --count <target-remote>/<base>...HEAD # behind, ahead
git merge-tree --write-tree --name-only <target-remote>/<base> HEAD # non-zero exit means conflicts; nothing is writtenIf no remote points at the target, fetch the base by URL into a temporary ref, such as refs/smart-push/base, and delete that ref afterwards.
Being behind the base isn't a blocker. Report it. If conflicts are predicted, list the files and offer to merge the base in, rebase (only if the commits are still unpublished), or open the PR anyway. Don't pick for the user, and never resolve a conflict by choosing a side on your own.
git log <target-remote>/<base>..HEAD must show only the intended commits. If unrelated commits show up, for example from a stale fork main, stop and explain.
Push
git push -u <push-remote> HEAD:refs/heads/<branch>When the push is rejected:
- Non-fast-forward: Fetch and compare. If the remote branch has commits you don't have, show them and ask. The options are merging them, rebasing the local unpublished commits, or pushing under a new branch name. Use
--force-with-leaseonly on the user's explicit instruction. - Protected branch or ruleset: Report the message as-is. Don't look for a way around it.
- A pre-push hook failed: Treat it as a failed check (SKILL.md, step 4).
- 403, or authentication failed: Report which credential failed, and suggest
gh auth login,gh auth refresh -s repo, or checking SSH keys. Don't edit the git configuration.
Existing pull requests
Look for open PRs from this head on the target:
gh pr list --repo <target> --head <branch> --state all \
--json number,state,isDraft,url,title,baseRefName,headRefName,headRepositoryOwnerCount only PRs whose headRepositoryOwner.login is the push remote's owner.
- Open PR: Pushing updates it, so never open a second one. Edit the title or body only when the new commits change the scope, and show the edit in the approval gate. Keep anything a human added, and prefer appending an "Update" section to rewriting the whole description.
- The branch's PR was merged or closed: Don't add commits to it. Suggest a new branch from the updated base.
Creating the pull request
gh pr create --repo <target> --base <base> --head <push-owner>:<branch> \
--title "<title>" --body-file <tmpfile> [--draft]- Title: Follow the repository's PR title convention. Otherwise use the main commit's subject, or summarize several commits in the same style.
- Body: Read the template from the target's base branch, not your working tree (
git show <target-remote>/<base>:<path>). Look in.github/pull_request_template.md,.github/PULL_REQUEST_TEMPLATE.md,PULL_REQUEST_TEMPLATE.md,docs/pull_request_template.md, and.github/PULL_REQUEST_TEMPLATE/*.md(pick the template that fits the change). Fill the template honestly: tick only the boxes that are true, and keep its headings. When there's no template, use only the sections that have something real to say:
## Summary
## Why
## Implementation notes
## Testing
## Breaking changes / migration
## Risks / follow-upsUnder Testing, list the exact commands you ran and their results, plus what you didn't run and why. Don't add a "Generated with" footer or any other AI attribution.
Write the body to a temporary file and pass it with --body-file. Don't use --body with shell-quoted text, because the quoting can mangle it.
If PR creation fails after the push succeeded, the branch is still published. Report that, fix the cause if you can (auth, base name), and retry. Before retrying, check for an existing PR first, so you don't create a duplicate.
gh is missing or unauthenticated
git pushcan still work through the existing git credentials, but you can't confirm ownership withoutgh. Ask the user to confirm which remote is their fork before pushing.- Skip PR creation. Instead, give the compare URL:
https://github.com/<target>/compare/<base>...<push-owner>:<branch>?expand=1, along with the drafted title and body, and the commandgh auth login.
Non-GitHub hosts
Committing and pushing work the same way. For GitLab, Bitbucket, and other hosts, use their CLI (glab mr create) only if it is installed and authenticated. Otherwise give the merge request URL and the drafted description.