home / skills / project-n-e-k-o / n.e.k.o / push-to-pr

push-to-pr skill

safe

This skill pushes local commits to an existing PR source branch without creating new branches, ensuring compliant and gap-free updates.

npx playbooks add skill project-n-e-k-o/n.e.k.o --skill push-to-pr

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.6 KB

---
name: push-to-pr
description: Push commits to an existing GitHub PR's source branch. NEVER create new branches. Use when the user says "push to PR #N", "push到PR", or any variation meaning to push local commits onto an existing pull request. Covers finding the PR's head branch via GitHub API, setting up the correct remote, and pushing with HEAD:<branch> syntax.
---

# Push to PR

Push local commits to an existing PR's source branch. **Never create new branches.**

## Workflow

### 1. Find PR head branch

```bash
curl -s https://api.github.com/repos/{OWNER}/{REPO}/pulls/{N} \
  | python3 -c "import sys,json; p=json.load(sys.stdin); print(f\"branch={p['head']['ref']}\nclone_url={p['head']['repo']['clone_url']}\ncan_modify={p['maintainer_can_modify']}\")"
```

- `head.ref` = branch name (e.g. `active_visual_chat`)
- `head.repo.clone_url` = fork URL
- `maintainer_can_modify` must be `true`

### 2. Ensure remote exists

```bash
git remote -v  # check if clone_url already listed
git remote add <name> <clone_url>  # only if missing
```

### 3. Fetch + rebase if needed

```bash
git fetch <remote> <branch>
# If local commits not on top:
git rebase <remote>/<branch>
```

### 4. Push

```bash
git push <remote> HEAD:<branch>
```

## Critical Rules

1. **NEVER** create new branches on any remote
2. **NEVER** `git push <remote> <local_branch>` if local branch differs from PR branch — always use `HEAD:<pr_branch>`
3. Branch name comes **only** from `head.ref` in API response
4. If `maintainer_can_modify` is `false`, inform user — cannot push
5. If push rejected (non-fast-forward), fetch and rebase first

Overview

This skill pushes local commits to an existing GitHub pull request by updating the PR’s source branch on the fork. It never creates new branches and enforces safe push rules so you don't accidentally overwrite or mis-target another branch. Use it when you want to update an open PR with local work and the PR allows maintainers to modify the branch.

How this skill works

The skill queries the GitHub API to read the PR’s head.ref and the fork clone URL and checks whether maintainers can modify the branch. It ensures the remote for that fork exists, fetches the PR branch, rebases local commits if needed, then pushes using the form HEAD:<pr_branch> to avoid mismatched branch names. It refuses to create any new branches or push directly to a differently named local branch.

When to use it

You need to push local commits to an existing GitHub PR's source branch
You have a local fix or update intended for an open PR and want to preserve PR branch name
When the user explicitly says “push to PR”
When the PR's maintainer_can_modify is true and you have appropriate local commits

Best practices

Always derive the branch name from the PR API head.ref — never guess or hardcode names
Ensure the remote for the PR fork exists before pushing; add it only if missing
Use git fetch <remote> <branch> and rebase local commits if push is rejected as non-fast-forward
Push using git push <remote> HEAD:<branch> to avoid pushing a mismatched local branch
If maintainer_can_modify is false, notify the user and do not attempt the push

Example use cases

Update an open PR after running new tests locally without creating additional branches
Push a small bugfix or formatting change to the PR author’s branch when maintainers are allowed to modify it
Recover from a push-rejected error by fetching and rebasing onto the remote PR branch before retrying
Scripted CI step that updates a PR branch with generated artifacts, following the HEAD:<branch> push pattern

FAQ

What if the remote rejects the push as non-fast-forward?

Fetch the remote branch and rebase your local commits onto it, then push again with HEAD:<branch>.

Can this skill create a new branch on the remote?

No. It will never create new branches; branch names are taken only from the PR head.ref and pushes use HEAD:<pr_branch>.