Edit GitHub Repository Settings with gh repo edit

One flag on gh repo edit can cost a repository its stars, its forks and its Actions history in a single command. Most of what it changes is far more ordinary than that, and this guide covers both kinds. It uses the installed GitHub CLI 2.87.3 and takes about five minutes if you are already authenticated.

Before you start

You need the gh package, an authenticated GitHub account, and permission to administer the target repository. Check the local version and login state first; these commands do not change repository settings.

gh --version
gh auth status

Expected version output on the machine used for this guide begins with:

gh version 2.87.3

If authentication is missing, stop at this checkpoint and run gh auth login interactively. Do not put an access token in a command line, shell history or article script.

1. Choose the repository explicitly

Inside a local checkout, gh repo edit uses the repository associated with the current directory. An explicit OWNER/REPO argument is safer for an administrative script, because it stops a changed directory or copied command from targeting the wrong project.

repo='OWNER/REPO'
gh repo view "$repo" --json nameWithOwner,visibility,defaultBranchRef,description

Replace OWNER/REPO with the real owner and repository name. Confirm the name, current visibility and default branch before proceeding. If the command reports that the repository cannot be found, check both the spelling and your account's access.

2. Make a small metadata change

Descriptions, homepages and topics are usually low-risk changes. The flags accept the replacement description or URL; --add-topic adds a topic and --remove-topic removes one. Use one deliberate command so the audit trail and later verification stay clear.

gh repo edit "$repo"   --description 'Short description for the project'   --homepage 'https://example.org/project'   --add-topic command-line

There is normally no success payload to parse. A zero exit status means the request completed; verify the values with:

gh repo view "$repo" --json description,homepageUrl,repositoryTopics   --jq '{description: .description, homepage: .homepageUrl, topics: [.repositoryTopics[].name]}'

To undo these particular changes, run another edit with the previous description and homepage, remove the topic, or use an empty value where GitHub accepts one. Keep the old values noted before changing them in case you need to restore them.

3. Change repository features deliberately

For example, this enables issues and the wiki, allows pull requests to update their head branches when behind the base branch, and deletes head branches after a merge:

gh repo edit "$repo"   --enable-issues   --enable-wiki   --allow-update-branch   --delete-branch-on-merge

Review the resulting settings in GitHub, or query the relevant fields through the API, before relying on them in automation. A successful CLI exit does not mean every repository policy now matches your intention, since another administrator or an organisation policy can change it later.

Merge-related flags include --enable-merge-commit, --enable-rebase-merge, --enable-squash-merge and --enable-auto-merge. These affect how pull requests can be merged; treat them as team policy, and check branch protection and required reviews separately before changing them. With squash merging enabled, current gh versions also support --squash-merge-commit-message with the values default, pr-title, pr-title-commits or pr-title-description.

4. Treat visibility as a breaking change

Current gh versions require an explicit acknowledgement flag:

gh repo edit "$repo"   --visibility private   --accept-visibility-change-consequences

Use one of public, private or internal. The acknowledgement confirms that you accept the consequences; it does not provide a rollback. To recover, run a new visibility change after checking the consequences again: public forks and repository history may not return to their previous arrangement automatically.

Common traps

• Hidden flags. The installed manpage may not show every flag in the installed binary. On this machine, gh repo edit --help also lists visibility acknowledgement, advanced security, secret scanning and squash-message options. Use the local help output as the final authority for the installed version.
• Unquoted arguments. A repository argument can be an OWNER/REPO name or a GitHub URL. Quote shell variables and URLs so punctuation is not interpreted by the shell.
• Permission errors. Some settings require organisation or repository administration rights. Adding sudo does not fix a permission error, because gh talks to GitHub using your account; use an account with the required role instead.
• Topic changes. Adding a topic and removing a topic are separate operations. Recheck the final topic list rather than assuming a command changed only the item you had in mind.