Edit GitHub Repository Settings Safely with gh repo edit

Use gh repo edit to change a repository description, homepage, topics, branch policy and selected GitHub features from a terminal. This guide 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 prevents 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 are 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 before changing them if you may need to restore them.

Checkpoint: confirm the intended policy

Feature flags are state changes, not a display of the current state. In this command, an enabling flag such as --enable-issues turns a feature on. To turn a supported setting off, append =false, for example --enable-projects=false. Do not assume that omitting a flag disables anything: omitted settings are left alone.

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 that every repository policy now matches your intention if another administrator or 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: 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

Changing visibility can lose stars and watchers, detach public forks from the network, disable push rulesets and expose GitHub Actions history and logs. It is not an ordinary metadata edit. Before running it, record the current state, agree the change with repository owners and check its effect on forks, workflows and sensitive history.

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

• 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.
• 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.
• Some settings require organisation or repository administration rights. A permission error is not fixed by adding sudo; gh talks to GitHub using your account, so use an account with the required role.
• 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.

Done means

• gh auth status identifies the intended GitHub account.
• gh repo view "$repo" confirmed the target before editing.
• The command changed only the settings you reviewed.
• A follow-up view or API query confirms the new values.
• Any visibility or merge-policy change has an agreed recovery plan.