checkout-pr git:20260312.0a0a896A

Immutable. This exact content is served forever at /api/v1/blob/2cb23b5af7306e3d.

---
name: checkout-pr
description: Add a remote for a given PR's head repository and checkout a local pr-xxx-work branch. Use when the user wants to work on someone else's PR locally.
---

# Checkout PR Workflow

Add a remote for a PR's head repository (if not already added) and checkout a local working branch.

## Input

Accept PR number (`123`, `#123`). Required.

## Setup

1. [Setup](../../lib/github/setup.md) — authenticate and detect context (role, remotes, state)

## Step 1: Fetch PR Metadata

```bash
PR_DATA=$(gh pr view $PR_NUMBER --repo "$PR_REPO_OWNER/$PR_REPO_NAME" --json \
  number,title,headRefName,headRepository,headRepositoryOwner,\
  baseRefName,state,maintainerCanModify,author)

HEAD_BRANCH=$(echo "$PR_DATA" | jq -r '.headRefName')
HEAD_REPO_OWNER=$(echo "$PR_DATA" | jq -r '.headRepositoryOwner.login')
HEAD_REPO_NAME=$(echo "$PR_DATA" | jq -r '.headRepository.name')
PR_AUTHOR=$(echo "$PR_DATA" | jq -r '.author.login')
MAINTAINER_CAN_MODIFY=$(echo "$PR_DATA" | jq -r '.maintainerCanModify')
PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
```

Validate PR state: OPEN (continue), CLOSED (warn user), MERGED (exit).

## Step 2: Add Remote (if needed)

If the PR head is on the canonical repo (`$HEAD_REPO_OWNER == $UPSTREAM_OWNER`), use the existing `upstream` remote. Otherwise, use the PR author's username as the remote name.

```bash
if [ "$HEAD_REPO_OWNER" = "$UPSTREAM_OWNER" ]; then
  # PR branch is on the canonical repo — use upstream
  FORK_REMOTE="upstream"
else
  # PR branch is on a fork — use author name as remote
  FORK_REMOTE="$HEAD_REPO_OWNER"
  if git remote | grep -q "^${FORK_REMOTE}$"; then
    echo "Remote '$FORK_REMOTE' already exists, fetching latest..."
  else
    git remote add "$FORK_REMOTE" \
      "git@github.com:$HEAD_REPO_OWNER/$HEAD_REPO_NAME.git"
  fi
fi

git fetch "$FORK_REMOTE" "$HEAD_BRANCH"
```

## Step 3: Checkout Work Branch

Run [checkout-fork-branch](../../lib/github/checkout-fork-branch.md) with `PUSH_REMOTE=$FORK_REMOTE` and `HEAD_BRANCH` from Step 1.

## Step 4: Report

Print summary:

```
Checked out PR #$PR_NUMBER ($PR_AUTHOR)
  Remote: $FORK_REMOTE -> git@github.com:$HEAD_REPO_OWNER/$HEAD_REPO_NAME.git
  Branch: $LOCAL_BRANCH -> $FORK_REMOTE/$HEAD_BRANCH
  Push:   PUSH_REMOTE=$FORK_REMOTE  BRANCH_NAME=$LOCAL_BRANCH:$HEAD_BRANCH
```

Remind user that `/github-pr` and `/address-pr-comments` will pick up the correct push target automatically (via upstream tracking).