Home / Alt manpages / gh-repo-rename(1)

  • gh-repo-rename(1)
  • User command
  • linux

Rename a GitHub Repository Safely with gh repo rename

Rename the wrong repository with gh repo rename and you have changed a remote that other people and other tools depend on, not just a local folder. This guide gets you a controlled rename, a check that you hit the right target, and updated Git remotes afterwards. Allow about ten minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • You need: gh, an authenticated GitHub CLI session with administrator access to the repository, and a local clone if you want to update its remote. No command here needs sudo.

The examples use GitHub CLI 2.87.3, installed here as Ubuntu package gh 2.45.0-1ubuntu0.3+esm3.

1. Check the installed command

Read the local command help before changing anything. This is an ordinary, read-only check:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh repo rename --help
Rename a GitHub repository.

USAGE
  gh repo rename [<new-name>] [flags]

The command takes one optional new repository name. The installed manual documents two useful flags: --repo selects a repository in [HOST/]OWNER/REPO form, and --yes skips the confirmation prompt. The new name is the repository name only, without the owner.

Checkpoint

Make sure the version and syntax match the command you are about to run. If this machine uses a different release, run its help again and treat that output as authoritative.

2. Confirm the repository and the new name

A rename is a remote state change, so write down the old full name and the exact new name before you open the prompt:

$ OLD_REPO='OWNER/old-repository'
$ NEW_NAME='new-repository'
$ printf 'Will rename %s to %s/%s\n' "$OLD_REPO" "${OLD_REPO%%/*}" "$NEW_NAME"
Will rename OWNER/old-repository to OWNER/new-repository

Replace both placeholder values with real ones. Keep NEW_NAME as a simple repository name, not OWNER/new-repository: the command does not use an owner in the new-name argument.

If you are standing inside the local clone of the repository, the shortest form targets the current repository:

$ gh repo rename "$NEW_NAME"
? Rename repository OWNER/old-repository to new-repository? Yes

Do not answer the prompt until the displayed owner and old repository name are correct. A typo in the destination is a change to the wrong remote, not a local filename mistake.

3. Select another repository explicitly

Use --repo when your current directory is unrelated, or when you want the target to be obvious in a script review:

$ gh repo rename --repo "$OLD_REPO" "$NEW_NAME"
? Rename repository OWNER/old-repository to new-repository? Yes

The short spelling is gh repo rename -R OWNER/old-repository new-repository. For a GitHub Enterprise host, include the host, for example ghe.example/OWNER/old-repository. The owner stays in the selector; it is not copied into the new-name argument.

Keep the confirmation prompt for an interactive one-off operation:

$ gh repo rename --repo "$OLD_REPO" "$NEW_NAME" --yes

Warning

--yes removes the last human check immediately before the rename. Only use it after the target has been independently checked in automation, and never combine it with an unreviewed value from an issue, pull request or other external input.

4. Verify the new repository

After a successful rename, ask GitHub CLI to view the new repository. This confirms the destination rather than relying only on the absence of an error:

$ NEW_REPO="${OLD_REPO%%/*}/$NEW_NAME"
$ gh repo view "$NEW_REPO" --json nameWithOwner --jq .nameWithOwner
OWNER/new-repository

The command should print the expected owner and new name. If it fails, check authentication and the spelling of NEW_REPO; do not repeat the rename with another guessed name.

5. Update a local clone

GitHub redirects normal web and Git operations from the old repository location, but a local remote should still be updated so future commands show the correct destination. Inspect the current remote first:

$ git remote -v
origin  [email protected]:OWNER/old-repository.git (fetch)
origin  [email protected]:OWNER/old-repository.git (push)

Then replace only the remote URL, from the clone whose origin you just inspected:

$ git remote set-url origin "[email protected]/${NEW_REPO}.git"
$ git remote -v
origin  [email protected]:OWNER/new-repository.git (fetch)
origin  [email protected]:OWNER/new-repository.git (push)

If your clone uses HTTPS, preserve that style instead:

$ git remote set-url origin "https://github.com/${NEW_REPO}.git"

Recovery

This local edit is reversible. Save the old URL first with git remote get-url origin. To undo it, run git remote set-url origin OLD_URL with that saved value; this does not rename the GitHub repository back.

GitHub preserves redirects for many repository pages, issues, stars, and ordinary Git clone, fetch and push operations. It does not redirect calls to an action hosted by a renamed repository. Search workflows, documentation, deployment configuration and package metadata for the old owner/name and update them deliberately.

$ rg -n --hidden --glob '!.git' 'OWNER/old-repository|old-repository' .
  • Reusable workflow references such as OWNER/old-repository/.github/workflows/... need updating by hand.
  • Badges, container image names and URL-building scripts are easy to miss and worth a dedicated search pass.
  • A rename is not a transfer of ownership. Moving the repository to another user or organisation needs separate GitHub steps.

There is no local undo flag in gh repo rename. To reverse the remote change, run the same command with the original repository name after checking the target and dependencies again. Treat that as another deliberate remote change, not a routine rollback.

Done means

  • The installed gh version and local help matched the syntax used.
  • The owner, old name and new name were checked before confirmation.
  • gh repo view reports the expected new repository name.
  • Each affected clone has an origin URL using the new name.
  • Workflows, action references and deployment links no longer depend on the old name where redirects are not enough.
  • You saved the old remote URL and know that reversing the remote rename is a second rename operation.