Change Codespace Port Visibility with gh codespace ports

gh codespace ports visibility switches a forwarded GitHub Codespaces port between public, private and organisation-only access. Allow about five minutes if you already know the codespace name and port numbers, since a typo here changes who can reach a running service.

This guide uses GitHub CLI 2.87.3, installed on this machine on 23 September 2026. Other releases may add behaviour, but the syntax below comes from the installed manual and matches the current upstream CLI manual.

1. Check the installed command

Start with read-only checks. None of them need 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

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

Each argument is a port number, a colon, and one visibility value, and you can pass several 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 the exact port number from the Ports panel or from whatever started the service; a forwarded port is not always the same number as the application port you meant to expose. A web application might listen on 3000, say, while another service on the same codespace 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, with no angle brackets. The command also inherits repository filters if you prefer those:

$ gh codespace ports visibility --repo OWNER/REPOSITORY 3000:private
$ gh codespace ports visibility --repo-owner OWNER 3000:private

These flags only help gh pick the codespace; they never change the port number or visibility themselves.

3. Make a port private

Private is the sensible starting point for a development server, a test dashboard, or anything holding 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 has no real success message, so shell status is your first check: zero means gh accepted the operation, not that the application itself is healthy. Refresh the Ports panel and confirm port 3000 shows private before you share its URL.

A private forwarded port stays reachable to you through the normal Codespaces access path. Other tools may still need their own authentication for it. Never paste a private port's URL or token into an issue, chat room or log while you are testing it.

4. Share only with your organisation

Use org when a service needs to reach members of the GitHub organisation without being open to anyone who finds the URL:

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

GitHub's documentation says organisation-private port sharing needs GitHub Team or GitHub Enterprise Cloud, and an organisation policy can restrict which visibility choices are allowed at all. If this fails, ask an organisation owner to check policy rather than retrying with different values.

5. Make a port public only for a deliberate reason

When the application really is meant for public testing, change only the port that needs it:

$ 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 someone who is not signed in to GitHub to confirm it behaves the way you expect. Check the application's own authentication and data handling too: port visibility never makes an unsafe application safe.

6. Change several ports together

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

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

Read the whole command before pressing Enter. A visibility change is not an application restart and does not stop whatever is listening on the port; it only changes who can reach the forwarded endpoint.

7. Recover from a mistake

There is no separate undo subcommand. Restore the previous visibility by running the same command with the value you actually want, for example closing a public test endpoint straight back down:

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

Confirm the setting in the Ports panel afterwards. If the application exposed credentials, personal data or an administrative action while it was public, treat that as an incident: revoke or rotate anything affected and review access logs. Switching the port back to private does not erase copies of data already taken.

Common traps

• gh selects the wrong codespace. Repeat the command with --codespace, or use the inherited repository filters.
• The port will not change. Check it is actually forwarded, that you are authenticated to the owning account, and that organisation policy allows the visibility you asked for.
• org is rejected. The organisation's plan may not support organisation-private sharing.

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