Merge pull request #5413 from github/repo-sync

repo sync

content/github/developing-online-with-codespaces/configuring-codespaces-for-your-project.md

@@ -25,20 +25,23 @@ You can create a default codespace configuration using a pre-built container con
 
 {% data variables.product.prodname_codespaces %}  uses settings contained in a configuration file named `devcontainer.json`. {% data reusables.codespaces.devcontainer-location %}
 
-You can use your `devcontainer.json` to set default settings for the entire codespace environment, including the {% data variables.product.prodname_vscode %} editor, but you can also set editor-specific settings in a file named `.vscode/settings.json`.
+Each new codespace created from a branch that contains the `.devcontainer` folder will be configured according to the folder's contents. For more information, see "[Creating a codespace](/github/developing-online-with-codespaces/creating-a-codespace)."
 
-Changes to a repository's codespace configuration apply only to every new codespace and do not affect any existing codespace.
+You can use your `devcontainer.json` to set default settings for the entire codespace environment, including the {% data variables.product.prodname_vscode %} editor, but you can also set editor-specific settings in a file named `.vscode/settings.json`.
 
 ### Using a pre-built container configuration
 
-You can use any pre-built container configuration for {% data variables.product.prodname_vscode %} that is available in the [`vscode-dev-containers`](https://github.com/microsoft/vscode-dev-containers) repository. Pre-built container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed.
+Pre-built container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed.
 
-1. Clone or download the [`vscode-dev-containers`](https://github.com/microsoft/vscode-dev-containers) repository.
-1. In the `vscode-dev-containers` repository, navigate to the [`containers`](https://github.com/microsoft/vscode-dev-containers/tree/master/containers) folder, then choose a container configuration for your project's needs. We'll use the [Node.js & JavaScript](https://aka.ms/vscode-dev-containers/definitions/node) container configuration as an example.
-1. From the [`Node.js & JavaScript`](https://aka.ms/vscode-dev-containers/definitions/node) folder, copy the `.devcontainer` folder to the root of your project's repository.
-1. Commit and push the new configuration to your project's repository on {% data variables.product.prodname_dotcom %}.
-
-Each new codespace created from a branch which contains the `.devcontainer` folder will be configured according to the folder's contents. For more information, see "[Creating a codespace](/github/developing-online-with-codespaces/creating-a-codespace)."
+1. Access the command palette (`shift command P` / `shift control P`), then start typing "Codespaces: Add Development Container Configuration Files...". Click **Codespaces: Add Development Container Configuration Files...**
+  !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
+1. Click the definition you want to use.
+  ![List of predefined container definitions](/assets/images/help/codespaces/predefined-container-definitions-list.png)
+1. Follow the prompts to customize your definition.
+1. Click **OK**.
+  ![OK button](/assets/images/help/codespaces/prebuilt-container-ok-button.png)
+1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
+  !["Codespaces: Rebuild Container" in the command palette](/assets/images/help/codespaces/rebuild-prompt.png)
 
 ### Creating a custom codespace configuration
 
@@ -53,6 +56,8 @@ You can define default editor settings for {% data variables.product.prodname_vs
 * Editor settings defined in `.vscode/settings.json` are applied as _Workspace_-scoped settings in the codespace.
 * Editor settings defined in the `settings` key in `devcontainer.json` are applied as _Remote [Codespaces]_-scoped settings in the codespace.
 
+After updating the `devcontainer.json` file, you can rebuild the container for your codespace to apply the changes. For more information, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
+
 ### Supported codespace configuration keys
 
 You can use configuration keys supported by {% data variables.product.prodname_codespaces %} in `devcontainer.json`.
@@ -80,3 +85,15 @@ You can use configuration keys supported by {% data variables.product.prodname_c
 - `dockerComposeFile`
 
 For more information about the available settings for `devcontainer.json`, see [devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json) in the {% data variables.product.prodname_vscode %} documentation.
+
+### Applying changes to your configuration
+
+{% data reusables.codespaces.apply-devcontainer-changes %}
+
+1. {% data reusables.codespaces.rebuild-command %}
+  !["Codespaces: Rebuild Container" in the command palette](/assets/images/help/codespaces/rebuild-container-command.png)
+1. {% data reusables.codespaces.recovery-mode %} Fix the errors in the configuration.
+  ![Error message about recovery mode](/assets/images/help/codespaces/recovery-mode-error-message.png)
+   - To diagnose the error by reviewing the creation logs, click **View creation log**.
+   - To fix the errors identified in the logs, update your `devcontainer.json` file.
+   - To apply the changes, rebuild your container. {% data reusables.codespaces.rebuild-command %}

content/github/developing-online-with-codespaces/developing-in-a-codespace.md

@@ -11,36 +11,22 @@ topics:
   - codespaces
 ---
 
+### About development with {% data variables.product.prodname_codespaces %}
+
 {% data reusables.codespaces.release-stage %}
 
 {% data reusables.codespaces.use-visual-studio-features %}
 
+{% data reusables.codespaces.about-port-forwarding %} For more information, see "[Forwarding ports in your codespace](/github/developing-online-with-codespaces/forwarding-ports-in-your-codespace)."
+
+{% data reusables.codespaces.apply-devcontainer-changes %} For more information, see "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#apply-changes-to-your-configuration)."
+
 {% data reusables.codespaces.use-chrome %} For more information, see "[Troubleshooting your codespace](/github/developing-online-with-codespaces/troubleshooting-your-codespace)."
 
-### Connecting to a codespace from {% data variables.product.prodname_vscode %}
 {% data reusables.codespaces.connect-to-codespace-from-vscode %}
 
 ### Navigating to your codespace
+
 {% data reusables.codespaces.navigate-to-codespaces %}
 2. Click the name of the codespace you want to develop in.
-  ![Name of codespace](/assets/images/help/codespaces/click-name-codespace.png)
-
-### Forwarding ports
-
-Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on port 3000, you can access the application from your browser to test and debug it.
-
-When an application running inside a codespace outputs a port to the console, {% data variables.product.prodname_codespaces %} detects the localhost URL pattern and automatically forwards those ports. You can click on the URL in the terminal to open it in a browser. For example, if an application outputs `http://127.0.0.1:3000` or `http://localhost:3000` to the console, the log would automatically convert the output to a clickable URL for port 3000.
-
-![Automatic Port Forwarding](/assets/images/help/codespaces/automatic-port-forwarding.png)
-
-Alternatively, you can also use any of the following ways to forward a port.
-
-* You can forward a port on demand by triggering the command palette (`shift command P` / `shift control P`) and typing "Codespaces: Forward Port". You can then enter the number of the port you want to forward.
-
-    ![Command Palette Port Forwarding](/assets/images/help/codespaces/command-palette-port-forwarding.png)
-
-* You can automatically configure forwarded ports in a `.devcontainer.json` file using the `forwardPorts` property.
-
-* You can add or remove forwarded ports within the Remote Explorer extension. From the Remote Explorer you can copy and paste the URLs for forwarded ports, allowing you to access them through your browser.
-
-    ![Remote Explorer Port Forwarding](/assets/images/help/codespaces/remote-explorer-port-forwarding.png)
+  ![Name of codespace](/assets/images/help/codespaces/click-name-codespace.png)

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

@@ -0,0 +1,61 @@
+---
+title: Forwarding ports in your codespace
+intro: '{% data reusables.codespaces.about-port-forwarding %}'
+product: '{% data reusables.gated-features.codespaces %}'
+versions:
+  free-pro-team: '*'
+topics:
+  - codespaces
+---
+
+### About forwarded ports
+
+Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on port 4000, you can access the application from your browser to test and debug the application.
+
+When an application running inside a codespace outputs a port to the console, {% data variables.product.prodname_codespaces %} detects the localhost URL pattern and automatically forwards the port. You can click on the URL in the terminal to open the port in a browser. For example, if an application outputs `http://127.0.0.1:4000` or `http://localhost:4000` to the console, the log would automatically convert the output to a clickable URL for port 4000.
+
+![Automatic port forwarding](/assets/images/help/codespaces/automatic-port-forwarding.png)
+
+You can also forward a port manually, label forwarded ports, share fowarded ports publicly, and add forwarded ports to the codespace configuration.
+
+### Forwarding a port
+
+You can manually forward a port that wasn't forwarded automatically.
+
+{% data reusables.codespaces.navigate-to-ports-tab %}
+1. Under the list of ports, click **Add port**.
+  ![Add port button](/assets/images/help/codespaces/add-port-button.png)
+1. Type the port number or address, then press enter.
+  ![Text box to type port button](/assets/images/help/codespaces/port-number-text-box.png)
+
+### Labeling a port
+
+You can label a port to make the port more easily identifiable in a list.
+
+{% data reusables.codespaces.navigate-to-ports-tab %}
+1. Hover over the port you want to label, then click the label icon.
+  ![Label icon for port](/assets/images/help/codespaces/label-icon.png)
+{% data reusables.codespaces.type-port-label %}
+
+### Sharing a port
+
+If you want to share a forwarded port with others, you can make the port public. After you make a port public, anyone with the port's URL can view the running application without needing to authenticate.
+
+{% data reusables.codespaces.navigate-to-ports-tab %}
+1. Right click the port you want to share, then click **Make 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)
+1. Send the copied URL to the person you want to share the port with.
+
+### Adding a port to the codespace configuration
+
+You can add a forwarded port to the {% data variables.product.prodname_codespaces %} configuration for the repository, so the port will automatically be forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information, see "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces#applying-changes-to-your-configuration)."
+
+You can manually configure fowarded ports in a `.devcontainer.json` file using the `forwardPorts` property, or you can use the "Ports" panel in your codespace.
+
+{% data reusables.codespaces.navigate-to-ports-tab %}
+1. Right click the port you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.
+  ![Option to set label and add port to devcontainer.json in the right-click menu](/assets/images/help/codespaces/update-devcontainer-to-add-port-option.png)
+{% data reusables.codespaces.type-port-label %}
+

content/github/developing-online-with-codespaces/index.md

@@ -20,6 +20,7 @@ topics:
 {% link_in_list /configuring-codespaces-for-your-project %}
 {% link_in_list /creating-a-codespace %}
 {% link_in_list /developing-in-a-codespace %}
+{% link_in_list /forwarding-ports-in-your-codespace %}
 {% link_in_list /personalizing-codespaces-for-your-account %}
 {% link_in_list /managing-encrypted-secrets-for-codespaces %}
 {% link_in_list /managing-access-and-security-for-codespaces %}

content/github/developing-online-with-codespaces/troubleshooting-your-codespace.md

@@ -16,6 +16,14 @@ topics:
 
 {% data reusables.codespaces.unsupported-repos %}
 
+{% data reusables.codespaces.recovery-mode %}
+
+```
+This codespace is currently running in recovery mode due to a container error.
+```
+
+Review the creation logs, update the configuration as needed, and run the "Rebuild Container" command to retry. For more information, see "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#apply-changes-to-your-configuration)."
+
 If you encounter issues while using a browser that is not Chromium-based, try switching to a Chromium-based browser, or check for known issues with your browser in the `microsoft/vscode` repository by searching for issues labeled with the name of your browser, such as[`firefox`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+label%3Afirefox) or [`safari`](https://github.com/Microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Asafari).
 
 If you encounter issues while using a Chromium-based browser, you can check if you're experiencing another known issue with {% data variables.product.prodname_vscode %} in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues) repository.

data/reusables/codespaces/about-port-forwarding.md

@@ -0,0 +1 @@
+You can forward ports in your codespace to test and debug your application.

data/reusables/codespaces/apply-devcontainer-changes.md

@@ -0,0 +1 @@
+After the {% data variables.product.prodname_codespaces %} configuration for a repository changes, you can apply the changes to an existing codespace by rebuilding the container for the codespace.

data/reusables/codespaces/navigate-to-ports-tab.md

@@ -0,0 +1,2 @@
+1. In your codespace, under the text editor, click "Ports".
+    ![Ports tab](/assets/images/help/codespaces/ports-tab.png)

data/reusables/codespaces/rebuild-command.md

@@ -0,0 +1 @@
+Access the command palette (`shift command P` / `shift control P`), then start typing "Codespaces: Rebuild Container". Click **Codespaces: Rebuild Container**. 

data/reusables/codespaces/recovery-mode.md

@@ -0,0 +1 @@
+If changes to your codespace's configuration cause a container error, your codespace will run in recovery mode, and you will see an error message.

data/reusables/codespaces/type-port-label.md

@@ -0,0 +1,2 @@
+1. Type a label for your port, then press enter.
+  ![Text box to type label for port](/assets/images/help/codespaces/label-text-box.png)