Change GitHub Codespaces Port Visibility Safely with gh

You will change one or more forwarded GitHub Codespaces ports to public, private, or organisation-only access with gh codespace ports visibility. Allow about five minutes if you know the codespace name and port numbers. The command changes the sharing state of an existing forwarded port, so check the numbers carefully before running it.

This guide uses GitHub CLI 2.87.3, the version installed on this machine on 23 September 2026. Other releases may add behaviour, but the command syntax here is taken from the installed manual and the matching upstream CLI manual.

1. Check the installed command

Start with read-only checks. They do not require sudo or any other elevated privilege:

$ command -v gh
/usr/bin/gh
$ gh version
gh version 2.87.3 (2026-02-23)
$ gh codespace ports visibility --help
Change the visibility of the forwarded port

Checkpoint: the help output should show this shape:

gh codespace ports visibility <port>:{public|private|org}... [flags]

The port argument is a port number followed by a colon and one visibility value. The command can accept several of these arguments in one invocation. The literal value org means private to the organisation in GitHub's port-sharing interface.

2. Identify the target codespace and port

Use an exact port number from the Ports panel or from the workflow that started the service. A forwarded port is not necessarily the same thing as the application port you intended to expose. For example, a web application might listen on 3000, while another service uses 8000.

If more than one codespace could match your account, select one explicitly with --codespace or its short form -c:

$ gh codespace ports visibility --codespace CODESPACE_NAME 3000:private

Replace CODESPACE_NAME with the real name. Do not include the angle brackets. If you prefer repository filtering, the command also inherits --repo OWNER/REPOSITORY and --repo-owner OWNER. These flags help gh select the codespace; they do not change the port number or visibility.

Checkpoint: write down the exact target as PORT:VISIBILITY, for example 3000:private. This command changes a remote Codespaces setting, so a typo can expose a different forwarded service or make the intended service unavailable to its previous audience.

3. Make a port private

Private is the sensible starting point for a development server, test dashboard, or anything containing data that should not be public:

$ gh codespace ports visibility --codespace CODESPACE_NAME 3000:private
$ printf 'gh exit status: %s\n' "$?"
gh exit status: 0

The command normally has no useful success message, so the shell status is the first check. A zero status means gh accepted the operation. It does not test the application itself. Refresh the Codespaces Ports panel and confirm that port 3000 is marked private before sharing its URL.

A private forwarded port is still available to you through the normal Codespaces access path. Remote access from other tools may need authentication, depending on how the connection is made. Do not paste a private port URL or token into an issue, chat room, or log while testing it.

4. Share only with your organisation

Use org when the service needs to be reachable by members of the GitHub organisation, but should not be open to everyone who obtains the URL:

$ gh codespace ports visibility --codespace CODESPACE_NAME 3000:org
$ printf 'gh exit status: %s\n' "$?"
gh exit status: 0

GitHub's current documentation says that organisation-private port sharing is available when the organisation uses GitHub Team or GitHub Enterprise Cloud. An organisation policy can also restrict which visibility choices are allowed. If this operation fails, ask an organisation owner to check policy rather than repeatedly retrying with different values.

Checkpoint: confirm the port's label in the Ports panel and test access with a colleague who is inside the intended organisation. A successful command and a correct audience are separate checks.

5. Make a port public only for a deliberate reason

If the application is designed for public testing, make the decision explicit and change only the required port:

$ gh codespace ports visibility --codespace CODESPACE_NAME 8000:public
$ printf 'gh exit status: %s\n' "$?"
gh exit status: 0

Open the forwarded URL in a private browser window, or ask a tester who is not signed in to GitHub to confirm the intended public behaviour. Check the application's own authentication and data handling as well. Port visibility does not make an unsafe application safe.

6. Change several ports together

The ellipsis in the synopsis means that several PORT:VISIBILITY arguments can be supplied in one command. This example narrows a development setup to private access, shares an internal preview with the organisation, and leaves a deliberately public demo port public:

$ gh codespace ports visibility --codespace CODESPACE_NAME 3000:private 5000:org 8000:public
$ printf 'gh exit status: %s\n' "$?"
gh exit status: 0

Review the complete command before pressing Enter. A visibility change is not an application restart, and it does not stop the process listening on the port. It changes who can reach the forwarded endpoint.

7. Recover from a mistake

There is no separate undo subcommand in the installed manual. Restore the previous visibility by running the same command with the visibility you want. For example, immediately close a public test endpoint again:

$ gh codespace ports visibility --codespace CODESPACE_NAME 8000:private
$ printf 'gh exit status: %s\n' "$?"
gh exit status: 0

Then confirm the setting in the Ports panel. If the application exposed credentials, personal data, or an administrative action while public, treat the exposure as an incident: revoke or rotate affected credentials and review access logs. Changing the port back to private does not erase copies of data already retrieved.

Common failures

If gh selects the wrong codespace, repeat the command with --codespace or use the inherited repository filters. If the port cannot be changed, check that it is forwarded, that you are authenticated to the account owning the codespace, and that organisation policy permits the requested visibility. If org is rejected, the organisation may not have a plan that supports organisation-private sharing.

Do not add sudo to this command. The operation is an authenticated GitHub API action, not a local file or network configuration change. A zero exit status confirms the CLI operation, but the Ports panel and a carefully chosen access test confirm the result.