In GitHub Codespaces, how do private, organization and public port visibility differ, and how would you stop public forwarding across an organization?
answer
- who must sign in
- the default is the safe one
- restart resets the risky setting
- policies bind only what the organization pays for
basics
~20 sPrivate ports, the default, open only to the codespace's creator after GitHub sign-in; organization ports to signed-in organization members; public ports to anyone with the URL. A Port visibility policy removes Public, but only for organization-billed codespaces.
solid answer
~40 sA forwarded port in GitHub Codespaces is served on the internet at a `*.app.github.dev` URL, and its **visibility** decides who gets through. **Private**, the default, admits only the codespace's creator after authenticating to GitHub. **Private to Organization** admits signed-in members of the organization that owns the repository, and exists only on GitHub Team and Enterprise Cloud. **Public** needs no authentication: anyone holding the URL sees the app, which is how a pre-release build leaks. A public port reverts to private when the codespace restarts or the port is removed and re-added. To stop it organization-wide, an owner adds a Codespaces policy with a **Port visibility** constraint and clears Public (and Org if wanted); private forwarding cannot be disabled. The catch: policies bind only codespaces the organization pays for, so user-owned codespaces escape them.
code
bash · 11 lines# list forwarded ports and their current visibility
gh codespace ports
# share port 3000 with members of the owning organization only
gh codespace ports visibility 3000:org
# take it back to the default
gh codespace ports visibility 3000:private
# reach a private port from a script: send the codespace's token
curl https://CODESPACE_NAME-3000.app.github.dev/ -H "X-Github-Token: ghu_xxxxxxxx"go deeper
Know the three levels and that private is the default. Public means no sign-in at all.
Explain the org level's plan requirement, the revert-to-private triggers, and how a script reaches a private port with the token header.
Treat a public port as a leak path: set the Port visibility policy, know it binds only organization-billed codespaces and only new or restarted ones, and stop exposed codespaces.
Decide whether Org visibility is an acceptable sharing channel and align ownership settings so that the policy actually covers the people it targets.
## What forwarding exposes When an application inside a codespace listens on a TCP port, Codespaces can **forward** it. Ports are forwarded automatically when a `localhost` URL appears in terminal output, or manually from the Ports panel or the GitHub CLI. A forwarded port is reachable at `https://CODESPACE_NAME-PORT.app.github.dev`, a public internet address. Visibility, not the address, is what keeps strangers out. ## The three visibility levels | Visibility | Who can open the URL | Authentication | Availability | |---|---|---|---| | **Private** (default) | Only the codespace's creator | GitHub sign-in, via a cookie that expires after 3 hours | Always; cannot be disabled | | **Private to Organization** (`org` in the CLI) | Members of the organization that owns the repository | GitHub sign-in | GitHub Team and Enterprise Cloud only | | **Public** | Anyone who has the URL | None | Unless a policy removes it | Details that matter in practice: - **Every port starts private.** - A **public port reverts to private** when the port is removed and re-added, or when the codespace restarts. - Switching a public port's protocol to **HTTPS** changes its visibility back to private. - Scripts reaching a *private* port at the remote domain must send the codespace's `GITHUB_TOKEN` in an `X-Github-Token` header. That token starts with `ghu_`, changes on every restart, and must never be shared. ## Choosing a visibility for the job - **Checking your own work** in a browser: leave the port **private**. - **Showing a colleague** in the same organization: **Private to Organization**; they sign in, nobody else gets through. - **Receiving a callback from an outside service**, which cannot sign in to GitHub: this usually needs **public**, so open it for the test and close it straight after, or stop the codespace. - **Calling your own private port from a script**: keep it private and send the `X-Github-Token` header. The ports panel and `gh codespace ports` both show each port's current visibility, which makes a quick audit before sharing a link easy. ## How a leak happens A developer wants a designer to see a feature, right-clicks the port, picks **Public**, and pastes the URL into a chat. Until someone switches the port back or the codespace stops, everyone who sees that URL can load the unreleased app without signing in: link previews, forwarded messages, browser history on a shared machine. Nothing else closes it. **Private to Organization** usually serves the same purpose with a sign-in wall. ## Shutting public forwarding off Organization owners do this with a **Codespaces policy**: 1. In the organization's Codespaces settings, open **Policies** and create a policy. 2. Add the **Port visibility** constraint and clear **Public**, and **Org** too if only private forwarding should remain. 3. Apply it to all repositories, or to selected ones. How policies combine and when they bite: - An organization-wide policy sets the most permissive option any repository may have; repository-specific policies can only **restrict further**. Adding policies never widens the choice. - **Private forwarding can never be removed**: the service itself depends on it, for example to forward SSH on port 22. - New codespaces obey the policy at once. Existing codespaces keep running as they are until they stop or time out, and are subject to the policy **the next time they start**. ## Where the policy stops **Codespaces policies apply only to codespaces the organization pays for.** If someone creates a codespace for one of the organization's repositories at their own expense, that codespace is not bound by any policy, port visibility included. Closing the gap is an ownership decision: set codespace ownership to the organization and enable Codespaces for the people who need it, so that their codespaces on the organization's repositories are organization-billed and therefore policed. Codespaces created at a user's own expense, for example by people the organization has not enabled who open its public repositories, stay outside the policy. A policy also does not retract a URL that was already shared. The running codespace keeps its public port until it stops, so after a suspected leak, stop the codespace at once.
- An organization policy forbids public ports, yet a member still made one public. How can that happen?Either the codespace is billed to the member rather than the organization, so no policy binds it, or it was already running when the policy was saved and is not checked until its next start. Check who owns the codespace, move ownership to the organization for the people who need Codespaces, and stop any codespace still exposing the port.
- Why can't an organization disable private port forwarding as well?Codespaces relies on private forwarding to work as designed, for example to forward SSH on port 22. A Port visibility constraint can only clear the Org and Public options. Private ports also carry little exposure: only the creator can open them, after signing in to GitHub.
- A public port still requires viewers to sign in to GitHub.
- Organization owners can turn off private port forwarding too.
- A port visibility policy covers every codespace on the organization's repositories.
- Saving a port policy instantly closes public ports in running codespaces.
- Forwarded port URLs are hard to guess, so making a port public is harmless.