Give gh a Default Repository for One Git Directory

You will configure GitHub CLI to use a chosen GitHub repository whenever you run repository-aware gh commands from one local clone, then verify and undo that choice. This is useful when a directory has several remotes or when the repository name cannot be inferred from the remote you normally use.

Allow about ten minutes. You need GitHub CLI and an existing Git working tree with at least one remote that points to a repository you can access. The examples use gh 2.87.3, installed on this machine on 23 September 2026. The command writes repository-local Git configuration; it does not need sudo and does not change files on GitHub.

1. Check the command before changing the repository

Run the version and help checks from the clone you intend to configure. They are read-only:

$ gh --version
gh version 2.87.3 (2026-02-23)

$ gh repo set-default --help
USAGE
  gh repo set-default [<repository>] [flags]

FLAGS
  -u, --unset   Unset the current default repository
  -v, --view    View the current default repository

The installed package's manpage describes the same command and two options. The current help output also documents a remote name such as origin as a valid argument. Treat the exact help from the installed binary as the version-specific reference if your package is older or newer.

Checkpoint: make sure the prompt is in the intended working tree. This command reports its path without modifying anything:

$ git rev-parse --show-toplevel
/home/you/src/project

2. Inspect the remotes and choose the target

List the remotes before setting a default:

$ git remote -v
origin  [email protected]:ACME/widget.git (fetch)
origin  [email protected]:ACME/widget.git (push)
mirror  https://github.com/ACME/widget-mirror.git (fetch)
mirror  https://github.com/ACME/widget-mirror.git (push)

Use an owner and repository name when you want an unambiguous target, for example ACME/widget. You can also pass a Git remote name, such as origin, when that remote resolves to the right GitHub repository. Do not assume that origin is the correct choice: forks, mirrors and release remotes commonly make that assumption wrong.

A repository argument is not a new clone and does not alter the remote URL. It tells gh which repository to use for GitHub API operations that otherwise infer a target from the local checkout.

3. Set the default explicitly

For a precise, script-friendly choice, pass the repository in OWNER/REPOSITORY form:

$ gh repo set-default ACME/widget
$ gh repo set-default --view
ACME/widget

The successful set operation is normally quiet. The second command is the checkpoint: it should print the repository you intended. If it prints another repository, stop and investigate before creating an issue, pull request or release.

When the matching remote is already correct, the remote name is convenient:

$ gh repo set-default origin
$ gh repo set-default --view
ACME/widget

Under the hood, this selection is stored with the local Git repository. It follows that checkout, not every clone on the machine, so another working tree can have a different default. The setting is local metadata and is not included in a commit.

4. Use the default where it helps

The default repository is used by gh commands that query or act on a repository when you have not supplied another target. Typical examples include viewing or creating pull requests and issues, viewing or creating releases, and working with GitHub Actions:

$ gh pr list
$ gh issue list
$ gh release list
$ gh run list

These commands may still need authentication and the permissions required by the operation. A default repository does not grant access and does not override an explicit repository argument. Before any write operation, confirm the target with gh repo set-default --view and inspect the command's own help for its target options.

There is a deliberate boundary around secrets. The installed gh help says that the default repository is not used for managing repository and environment secrets. Do not infer a secret-management target from this setting. Supply the repository explicitly when the relevant command supports that option, and check the command's current help first.

5. Handle an ambiguous or invalid remote

If gh repo set-default REMOTE reports that none of the Git remotes correspond to a valid remote repository, check the remote URL and test the owner and repository spelling:

$ git remote get-url origin
[email protected]:ACME/widget.git
$ gh repo set-default ACME/widget
$ gh repo set-default --view
ACME/widget

A made-up placeholder such as example/project, a deleted repository or a remote on another Git host cannot become a valid GitHub default. Fixing a remote URL is a separate Git operation and can affect future fetches and pushes, so do not change it merely to silence this command. If the checkout is a fork or mirror, decide whether GitHub API queries should use that fork or the upstream repository, then set that owner and name explicitly.

If you run gh repo set-default with no argument, it opens an interactive picker. This can be useful when several remotes are valid. In a script or a repeatable setup note, use an explicit repository instead so the choice is visible and does not depend on terminal interaction.

6. Remove the local choice carefully

Unsetting is a local configuration change. It does not delete the repository, alter a remote, or remove anything from GitHub:

$ gh repo set-default --unset
$ gh repo set-default --view
X No default remote repository has been set. To learn more about the default repository, run: gh repo set-default --help

The exact diagnostic marker and wording can vary with the gh release. The useful result is that no repository name is shown as the current default. If your installed release starts an interactive prompt or rejects the option outside a terminal, use its own --help output and complete the removal interactively rather than editing Git configuration by guesswork.

There is no elevated-privilege recovery step. If you unset the wrong checkout's value, run gh repo set-default OWNER/REPOSITORY again from that checkout. If you need to recover after changing a remote URL, restore the previous URL with the normal git remote set-url workflow after checking it carefully.