skip to content

With the GitHub CLI, after `gh repo fork acme/widgets --clone`, which remotes exist and which repository does `gh pr create` target?

level: juniorimportance: should knowfreq 36%

answer

  1. two remotes, two roles
  2. your copy versus the parent
  3. the default repository gh queries
  4. push first, or name the head

basics

~10 s

origin points at your fork and upstream at acme/widgets, which gh marks as the default repository; gh pr create therefore opens the pull request against acme/widgets, using a head branch pushed to your fork.

solid answer

~40 s

`gh repo fork acme/widgets --clone` creates the fork under your account (or reuses it if it exists), clones it so `origin` is your fork, adds `upstream` for `acme/widgets`, fetches it and marks it as the **default repository**. That default is what `gh pr`, `gh issue`, `gh release` and `gh run` query, so `gh pr create` opens the pull request on `acme/widgets` with your fork's branch as the head. The base branch is `--base`, else the branch's `gh-merge-base` Git config, else the repository's default branch. If the branch is not pushed yet, gh prompts for where to push; without a terminal it aborts unless you push first or pass `--head`. `gh repo clone` of a fork sets up the same `upstream` remote, and `--no-upstream` (gh 2.88.0) skips it.

go deeper

for a junior

Recall the layout: origin is your fork, upstream is the parent, and gh pr create opens the pull request on the parent.

for a middle

Explain the default repository and how gh pr create picks base, head, title and body, including the non-interactive rules for pushing and filling.

for a senior

Diagnose a pull request opened in the wrong repository or a CI job that cannot create one, using gh repo set-default, --head and the gh-merge-base config.

for a principal

Weigh a fork-based contribution model against shared-repository branches for a team, and what each means for gh's defaults and for who can push to a pull request.

## The fork workflow in one command A **fork** is your own server-side copy of someone else's repository. Contributors without write access push their branches to the fork and open pull requests back to the original, called the **parent** or **upstream**. Setting that up by hand takes a fork in the browser, a clone, a second remote and a fetch. The GitHub CLI does all of it in one command: ```bash gh repo fork acme/widgets --clone ``` It does the following, in order: 1. **Creates the fork** under your account. `--org <name>` puts it in an organisation instead, `--fork-name` renames it, and `--default-branch-only` copies only the default branch. If you already have a fork, gh reports that it already exists and reuses it. 2. **Clones the fork**, so `origin` points at `alice/widgets`, your copy. 3. **Adds a remote named `upstream`** for `acme/widgets` and fetches it. 4. **Marks `upstream` as the default repository** and prints a note pointing at `gh repo set-default --help`. ## Why the default repository matters A clone with two remotes is ambiguous: when you type `gh issue list`, which repository's issues do you mean? gh settles it with the **default repository**, the remote marked for gh to query. According to the help for `gh repo set-default`, gh uses it for: - viewing and creating pull requests; - viewing and creating issues; - viewing and creating releases; - working with GitHub Actions runs. After a fork-and-clone the default is the parent. `gh issue list` shows `acme/widgets` issues, and `gh pr create` opens the pull request in `acme/widgets`. Check it with `gh repo set-default --view`, or change it with `gh repo set-default origin` when you really mean your fork. Repository and environment secrets are the stated exception: gh does not use the default repository to manage them. | Command | Remote layout afterwards | Default repository | |---|---|---| | `gh repo fork acme/widgets --clone` | `origin` = your fork, `upstream` = parent | parent | | `gh repo clone alice/widgets` (a fork) | `origin` = fork, `upstream` = parent | parent | | `gh repo clone alice/widgets --no-upstream` | `origin` only | the fork (`origin`) | | `gh repo fork --remote` inside a clone of the parent | old `origin` renamed to `upstream`, fork added as `origin` | see `gh repo set-default --view` | `gh repo clone` also accepts `--upstream-remote-name <name>` (the value `@owner` names the remote after the parent's owner). `--no-upstream` was added in **gh 2.88.0**. Running `gh repo fork` inside an existing clone of the parent offers to add a remote. With `--remote-name` you pick its name, and gh then does not rename your existing `origin`. ## What gh pr create does next On a feature branch in that clone, `gh pr create` works out three things. **The base.** The repository is the default repository. The branch is `--base` / `-B` if given, else the `gh-merge-base` value in the branch's Git config (`git config branch.<current>.gh-merge-base release/2.x`), else the repository's default branch. **The head.** If the branch is already pushed to a remote, gh uses it. If it is not, then: - in a terminal, gh asks where to push the branch, listing the remotes you can push to and, if you have no fork yet, offering to create one. A fork created this way gets only the parent's default branch; - without a terminal, as in a CI job, it stops with an error telling you to push the branch first or use `--head`; - `--head` / `-H` names the head branch outright (`<user>:<branch>` selects a user's fork) and skips any push or fork step. **Title and body.** - `--fill`: with one commit, the commit's subject and body; with several, the branch name made readable as the title and a bullet list of commit subjects as the body. - `--fill-first`: the first commit's subject and body. `--fill-verbose`: every commit's subject and body. - `--title` / `--body` override whatever a fill flag produced. - Without a terminal you must give `--title` and `--body` or one of the fill flags. **Other useful flags.** `--draft` opens the pull request as a draft. `--reviewer`, `--assignee`, `--label` and `--milestone` set metadata. `--no-maintainer-edit` stops users with write access to the base repository from pushing to your head branch. `--dry-run` prints what would be created, though the help warns it may still push Git changes. When it succeeds, `gh pr create` prints the new pull request's URL. ## Where the edges are - A pull request body that says `Closes #123` closes the issue on merge. That is GitHub's keyword behaviour, covered with issues and pull requests, not a gh feature. - Keeping your fork's default branch current is a Git or `gh repo sync` matter. It is separate from opening the pull request. - If `gh pr create` opens the pull request in the wrong repository, the first thing to check is the default repository, not the remotes.

  • `gh pr create` opened the pull request against your fork instead of the parent. What do you check?
    The default repository. `gh repo set-default --view` shows which repository gh queries; if it is your fork (for example after `gh repo clone --no-upstream`, or after someone ran `gh repo set-default origin`), run `gh repo set-default acme/widgets`, or pass `--repo acme/widgets` for a single command.
  • How do you make every pull request from a long-lived branch target `release/2.x` without typing `--base` each time?
    Set the branch's `gh-merge-base` Git config: `git config branch.<branch>.gh-merge-base release/2.x`. `gh pr create` uses it whenever `--base` is not given, and falls back to the repository's default branch otherwise.

  • gh pr create always targets whatever repository origin points at
  • gh repo fork --clone leaves you with a single remote for the fork
  • gh pr create --dry-run is guaranteed to make no git changes
  • --fill always uses the latest commit's message as the pull request title
  • In a CI job gh pr create pushes the branch for you automatically

Assumes gh 2.102; gh repo clone gained --no-upstream in gh 2.88.0 to skip the upstream remote when cloning a fork.