Merge pull request github#25487 from github/mm-cs-port-visibility

Adding port visibility docs

content/codespaces/codespaces-reference/security-in-codespaces.md

@@ -56,6 +56,8 @@ If you need to allow external access to services running on a codespace, you can
 
 If you need to connect to a service (such as a development web server) running within your codespace, you can configure port forwarding to make the service available on the internet. 
 
+Organization owners can restrict the ability to make forward ports available publicly or within the organization. For more information, see "[Restricting the visibility of forwarded ports](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports)."
+
 **Privately forwarded ports**: Are accessible on the internet, but only the codespace creator can access them, after authenticating to {% data variables.product.product_name %}.
 
 **Publicly forwarded ports within your organization**: Are accessible on the internet, but only to members of the same organization as the codespace, after authenticating to {% data variables.product.product_name %}.

content/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace.md

@@ -25,6 +25,12 @@ When an application running inside a codespace prints output to the terminal tha
 
 You can also forward a port manually, label forwarded ports, share forwarded ports with members of your organization, share forwarded ports publicly, and add forwarded ports to the codespace configuration.
 
+{% note %}
+
+**Note**: {% data reusables.codespaces.restrict-port-visibility %}
+
+{% endnote %}
+
 ## Forwarding a port
 
 You can manually forward a port that wasn't forwarded automatically.
@@ -85,12 +91,18 @@ To see details of forwarded ports enter `gh codespace ports` and then choose a c
 
 {% note %}
 
-**Note:** You can only make a port private to an organization if your organization uses {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %}. This feature is not currently available in the beta version of {% data variables.product.prodname_codespaces %}.
+**Note:** You can only make a port private to an organization if your organization uses {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %}.
 
 {% endnote %}
 
 If you want to share a forwarded port with others, you can either make the port private to your organization or make the port public. After you make a port private to your organization, anyone in the organization with the port's URL can view the running application. After you make a port public, anyone who knows the URL and port number can view the running application without needing to authenticate.
 
+{% note %}
+
+**Note:** Your choice of port visibility options may be limited by a policy configured for your organization. For more information, see "[Restricting the visibility of forwarded ports](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports)."
+
+{% endnote %}
+
 {% webui %}
 
 {% data reusables.codespaces.navigate-to-ports-tab %}
@@ -105,7 +117,7 @@ If you want to share a forwarded port with others, you can either make the port
 {% vscode %}
 
 {% data reusables.codespaces.navigate-to-ports-tab %}
-1. Right click the port you want to share, then click **Make Public**.
+1. Right click the port that you want to share, select the "Port Visibility" menu, then click **Private to Organization** or **Public**.
   ![Option to make port public in right-click menu](/assets/images/help/codespaces/make-public-option.png)
 1. To the right of the local address for the port, click the copy icon.
   ![Copy icon for port URL](/assets/images/help/codespaces/copy-icon-port-url.png)

content/codespaces/getting-started/quickstart.md

@@ -41,7 +41,7 @@ Once your codespace is created, your repository will be automatically cloned int
 
     If you're following along with a different application type, enter the corresponding start command for that project.
 
-2. When your application starts, the codespace recognizes the port the application is running on and displays a prompt to forward that port so you can connect to it. 
+2. When your application starts, the codespace recognizes the port the application is running on and displays a prompt to let you know it has been forwarded. 
 
   ![Port forwarding toast](/assets/images/help/codespaces/quickstart-port-toast.png)
 

content/codespaces/managing-codespaces-for-your-organization/index.md

@@ -14,6 +14,7 @@ children:
   - /managing-repository-access-for-your-organizations-codespaces
   - /reviewing-your-organizations-audit-logs-for-codespaces
   - /restricting-access-to-machine-types
+  - /restricting-the-visibility-of-forwarded-ports
 shortTitle: Managing your organization
 ---
 

content/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types.md

@@ -20,7 +20,7 @@ As an organization owner, you may want to configure constraints on the types of
 
 ### Behavior when you set a machine type constraint
 
-If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they time out. When the user attempts to resume the codespace they are shown a message telling them that the currenly selected machine type is no longer allowed for this organization and prompting them to choose an alternative machine type.
+If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they are stopped or time out. When the user attempts to resume the codespace they are shown a message telling them that the currenly selected machine type is no longer allowed for this organization and prompting them to choose an alternative machine type.
 
 If you remove higher specification machine types that are required by the {% data variables.product.prodname_codespaces %} configuration for an individual repository in your organization, then it won't be possible to create a codespace for that repository. When someone attempts to create a codespace they will see a message telling them that there are no valid machine types available that meet the requirements of the repository's {% data variables.product.prodname_codespaces %} configuration.
 

content/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports.md

@@ -0,0 +1,83 @@
+---
+title: Restricting the visibility of forwarded ports
+shortTitle: Restricting port visibility
+intro: 'You can set constraints on the visibility options users can choose when they forward ports from codespaces in your organization.'
+product: '{% data reusables.gated-features.codespaces %}'
+permissions: 'To manage access to port visibility constraints for the repositories in an organization, you must be an organization owner.'
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+---
+
+## Overview
+
+Typically, within a codespace you are able to forward ports privately (only to yourself), to members of your organization, or publicly (to anyone with the URL). For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)."
+
+As an organization owner, you may want to configure constraints on the visibility options users can set when forwarding ports. For example, for security reasons, you may want to disallow public port forwarding. You do this by defining one or more policies in the {% data variables.product.prodname_codespaces %} settings for your organization.
+
+### Behavior when you set a port visibility constraint
+
+If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they are stopped or time out. When the user resumes the codespace, it will be subject to the policy constraints.
+
+{% note %}
+
+**Note**: You can't disable private port forwarding, as private port forwarding is required by {% data variables.product.prodname_codespaces %} to continue working as designed, for example to forward SSH on port 22.
+
+{% endnote %}
+
+### Setting organization-wide and repository-specific policies
+
+When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of visibility options more, not less, restrictive.
+
+For example, you could create an organization-wide policy that restricts the visibility options to organization only. You can then set a policy for Repository A that disallows both public and organization visibility, which would result in only private port forwarding being available for this repository. Setting a policy for Repository A that allowed both public and organization would result in only organization visibility, because the organization-wide policy does not allow public visibility.
+
+If you add an organization-wide policy, you should set it to the most lenient visibility option that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice.
+
+## Adding a policy to limit the port visibility options
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Code, planning, and automation" section of the sidebar, select **{% octicon "codespaces" aria-label="The codespaces icon" %} {% data variables.product.prodname_codespaces %}** then click **Policies**.
+1. On the "Codespace policies" page, click **Create Policy**.
+1. Enter a name for your new policy.
+1. Click **Add constraint** and choose **Port visibility**.
+
+   ![Add a constraint for port visibility](/assets/images/help/codespaces/add-constraint-dropdown-ports.png)
+
+1. Click {% octicon "pencil" aria-label="The edit icon" %} to edit the constraint
+
+   ![Edit the port visibility constraint](/assets/images/help/codespaces/edit-port-visibility-constraint.png)
+
+1. Clear the selection of the port visibility options (**Org** or **Public**) that you don't want to be available.
+
+   ![Choose the port visibility options](/assets/images/help/codespaces/choose-port-visibility-options.png)
+
+1. In the "Change policy target" area, click the dropdown button.
+1. Choose either **All repositories** or **Selected repositories** to determine which repositories this policy will apply to.
+1. If you chose **Selected repositories**:
+   1. Click {% octicon "gear" aria-label="The settings icon" %}.
+
+      ![Edit the settings for the policy](/assets/images/help/codespaces/policy-edit.png)
+
+   2. Select the repositories you want this policy to apply to.
+   3. At the bottom of the repository list, click **Select repositories**.
+
+      ![Select repositories for this policy](/assets/images/help/codespaces/policy-select-repos.png)
+
+1. Click **Save**.
+
+## Editing a policy
+
+1. Display the "Codespace policies" page. For more information, see "[Adding a policy to limit the port visibility options](#adding-a-policy-to-limit-the-port-visibility-options)."
+1. Click the name of the policy you want to edit.
+1. Make the required changes then click **Save**.
+
+## Deleting a policy 
+
+1. Display the "Codespace policies" page. For more information, see "[Adding a policy to limit the port visibility options](#adding-a-policy-to-limit-the-port-visibility-options)."
+1. Click the delete button to the right of the policy you want to delete.
+
+   ![The delete button for a policy](/assets/images/help/codespaces/policy-delete.png)

content/codespaces/troubleshooting/troubleshooting-port-forwarding-for-codespaces.md

@@ -19,3 +19,5 @@ If port forwarding is set up, check the following:
 
 - Use the notification toast or click the URL in Terminal to open the forwarded port. Typing in `localhost:8000` (as an example) to your local machine will not work if you're connected to the codespace via the browser.
 - Make sure to check that your application is still running from within your codespace. If your codespace has stopped after a period of inactivity, you'll need to ensure to restart your application once the codespace has restarted.
+
+Typically, you can make a forwarded port accessible publicly, or within the organization that owns a repository. For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)." If either, or both, of the options for public or organization visibility are not available, this indicates that an organization-level policy has been configured. For more information, see "[Restricting the visibility of forwarded ports](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports)."

data/reusables/codespaces/restrict-port-visibility.md

@@ -0,0 +1 @@
+Organization owners can restrict the ability to make forward ports available publicly or within the organization. For more information, see "[Restricting the visibility of forwarded ports](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports)."