Skip to main content
skill CX Codex

fork-pr-operations — Claude Code skill: what it does, how to install

fork-pr-operations guides agents through fork pull request workflows: GitHub Actions approval, safe rebasing with force-with-lease, and handling multi-round bot reviews.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-code
Open on GitHub

What fork-pr-operations does

The skill establishes operational rules for fork PRs where GitHub enforces strict security defaults on external branches. It standardizes remote naming with origin for your fork and upstream for the base repository, provides a rebase procedure on top of upstream/main, and forbids standard force pushes in favor of git push --force-with-lease.

A central section handles CI runs. GitHub holds fork workflow runs in a waiting status until authorized. The skill provides CLI commands using gh run list and gh api, adding a five-second wait to prevent race conditions during run creation. Without actions: write access on the upstream repository, run approval calls fail: only upstream maintainers can approve those jobs.

It also defines an approach for automated review bots triggered on every push. The agent learns to ignore repetitive APPROVE comments from bots, verifies commit SHAs with gh pr view before cancelling obsolete checks, and focuses on actionable human feedback.

What it helps with

  • Sync fork branches with upstream/main using safe --force-with-lease pushes
  • Approve pending GitHub Actions workflow runs on upstream via gh CLI
  • Verify CI check statuses against the current PR head SHA after rebasing
  • Filter noise and duplicate findings from automated multi-round bot reviews

Example prompts for the agent

  • Rebase this fork branch onto upstream/main and push it safely using force-with-lease
  • Check pending GitHub Actions runs for our upstream PR and approve them
  • Inspect bot reviews on the latest push and list only newly reported issues

How to install fork-pr-operations

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-code

2Manually: put the files in place

~/.claude/skills/fork-pr-operations/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/fork-pr-operations/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about fork-pr-operations

How do I install fork-pr-operations in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-code. The file will be placed in ~/.claude/skills/fork-pr-operations/SKILL.md.

What does the fork-pr-operations skill do?

It guides coding agents through fork pull requests, covering remote configuration, safe rebasing, workflow approval via gh api, and bot review triage.

Can a fork author approve pending GitHub Actions runs?

Workflow approval via gh api requires actions: write permissions on the upstream repository. Contributors without upstream write access cannot approve runs; only upstream maintainers can.

Source text

SKILL.md · MIT
---
name: fork-pr-operations
description: Operational patterns for fork PRs (head repo differs from base repo). Covers GitHub workflow approval after push, force-push protocol, remote naming conventions, stale CI verification, and bot review multi-round awareness. Load when working with fork PRs, cross-repo contributions, or workflow approval issues.
metadata:
  audience: swarm-plugin
---

# Fork PR Operations

Fork PRs — where the head repository differs from the base repository — have a distinct operational lifecycle. GitHub treats them with stricter security defaults that require additional steps not needed for same-repo PRs.

## When to use this skill

- You are pushing to a branch on a forked repository
- CI checks are stuck in "waiting" status after a push
- You need to rebase a fork PR branch against upstream/main
- A bot reviewer posts after every push, creating multiple review rounds

## Workflow approval after push

**Critical:** GitHub requires explicit workflow approval for fork PRs. After every push, CI jobs remain in "waiting" status until a user with write access to the base repository approves the workflow run.

### Approval command

```bash
# List pending workflow runs for the PR
gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 5

# Approve a specific run
gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<run-id>/approve
```

### Race condition: run not yet created

After pushing, there is a brief window (1-5 seconds) before GitHub creates the workflow run object. If you try to approve too quickly, the run won't exist yet. Retry with a short delay:

```bash
# Wait for run to appear, then approve
sleep 5
gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 1 --json databaseId,status --jq '.[0]'
# If status is "waiting", approve:
gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<databaseId>/approve
```

### Permission requirements

The `gh api -X POST .../approve` call requires `actions: write` permission on the **base** (upstream) repository. This typically means your GitHub token needs the `repo` or `public_repo` scope, and you must have write access to the upstream repo. Fork owners without upstream write access cannot approve workflow runs — only upstream maintainers can.

```bash
gh auth status
# Verify you have repo/public_repo scope and write access to the upstream repo
```

## Remote naming conventions

Standard remote setup for fork-based contributions:

```bash
# origin = your fork
git remote add origin https://github.com/<your-username>/<repo>.git

# upstream = canonical repository
git remote add upstream https://github.com/<canonical-owner>/<repo>.git

# Additional forks by owner name (if collaborating across forks)
git remote add <collaborator> https://github.com/<collaborator>/<repo>.git
```

## Force-push protocol

Always use `--force-with-lease`, never bare `--force`:

```bash
# Safe: verifies remote tracking branch matches expected SHA
git push --force-with-lease origin <branch-name>

# DANGEROUS: overwrites any remote changes, including work by collaborators
git push --force origin <branch-name>  # NEVER DO THIS
```

`--force-with-lease` checks that the remote tracking branch matches your local expectation. If someone else pushed between your last fetch and your force-push, the lease check fails safely instead of destroying their work.

## Rebase workflow

To sync a fork PR branch with upstream/main:

```bash
# Fetch latest from upstream
git fetch upstream

# Rebase your branch onto upstream/main
git rebase upstream/main

# Resolve conflicts if any, then continue
git rebase --continue

# Force-push the rebased branch to your fork
git push --force-with-lease origin <branch-name>
```

After rebase + force-push, the PR head SHA changes. All CI checks re-trigger (subject to workflow approval for fork PRs).

## Stale CI verification

After a rebase or force-push, verify CI check data belongs to the current PR head:

```bash
# Get current PR head SHA
gh pr view <number> --repo <upstream-owner>/<upstream-repo> --json headRefOid --jq '.headRefOid'

# Check if CI checks match this SHA
gh pr checks <number> --repo <upstream-owner>/<upstream-repo> --json name,state,startedAt,completedAt
```

If check data references an older SHA, the checks are stale. Cancel obsolete runs only after confirming they are not the current head:

```bash
# Cancel a specific run (only if it's NOT the current head)
gh run cancel <run-id> --repo <upstream-owner>/<upstream-repo>
```

## Bot review multi-round awareness

Automated bot reviewers (e.g., hermes-pr-review) post a new review after **every push**. If you push N times, you get N bot reviews. This is expected behavior, not a bug.

### Strategy

1. **Ignore APPROVE rounds** from bots. A bot APPROVE after a trivial push adds no signal.
2. **Scan for new findings only.** Compare the latest bot review against prior rounds to identify newly raised issues.
3. **Focus on human reviewer findings.** Bot findings are advisory; human reviewer findings are binding.
4. **Do not attempt to silence the bot.** The multi-round pattern is by design.

## Cross-references

- `.claude/skills/commit-pr/SKILL.md` — PR publication protocol, including `--force-with-lease` guidance and remote check verification
- `.opencode/skills/swarm-pr-feedback/SKILL.md` — Feedback closure workflow for addressing review findings
- `.agents/skills/subprocess-safety/SKILL.md` — Subprocess safety for `gh` CLI calls

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Git and GitHub →

From the same set121

The whole set →
swarm-pr-feedback swarm-pr-feedback — a skill that works through PR feedback you already have: review notes, GitHub threads, failing checks, conflicts. Everything is verified against the code before a single edit lands. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that resolves pull request review comments, CI failures, and branch conflicts through structured verification stages. CX Codex +1 ★ 539repo stars commit-pr commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars test-file-split test-file-split breaks an oversized test file into parts along describe() boundaries when it nears the 500-line cap or blows past it. CX Codex +1 ★ 539repo stars parallel-work-check parallel-work-check is a Claude Code skill that compares local and remote commits on an existing branch and reviews new changes. It helps catch overlapping work before editing. CX Codex +1 ★ 539repo stars design-docs Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog. CX Codex +1 ★ 539repo stars orchestrating-subagents orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts. CX Codex +1 ★ 539repo stars commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open