docs: Connect visual studio code to workspace

modules/end-user-guide/nav.adoc

@@ -27,6 +27,7 @@
 * xref:devfile-introduction.adoc[]
 * xref:ides-in-workspaces.adoc[]
 ** xref:microsoft-visual-studio-code-open-source-ide.adoc[]
+** xref:connect-visual-studio-code-to-che-workspace.adoc[]
 ** xref:idea-ultimate.adoc[]
 ** xref:defining-a-common-ide.adoc[]
 * xref:using-credentials-and-configurations-in-workspaces.adoc[]

modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc

@@ -0,0 +1,116 @@
+[id="connect-visual-studio-code-to-che-workspace"]
+
+= Connecting Visual Studio Code to a {prod-short} workspace
+
+{prod} supports connecting your desktop Visual Studio Code to a running {prod-short} workspace over link:https://code.visualstudio.com/docs/remote/tunnels/[Remote Tunnels].
+
+.Connecting Visual Studio Code desktop to a new workspace
+
+Follow the steps below to connect a new workspace with your local Visual Studio Code.
+
+.Prerequisites
+
+. link:https://code.visualstudio.com/[Visual Studio Code] is installed.
+
+.Procedure
+
+. Create a workspace on the {prod-short} Dashboard and choose *Visual Studio Code (desktop)* as your editor.
++
+image::vscode-remote/select-editor.png[IntelliJ IDEA Ultimate on Dashboard,link="{imagesdir}/vscode-remote/select-editor.png"]
+
+. Wait for the login page to appear.
++
+image::vscode-remote/login.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/login.png"]
++
+
+. Log in with your Microsoft or GitHub account.
++
+Click the *Copy & Continue to Microsoft* or *Copy & Continue to GitHub* button to copy the authentication code to the clipboard and to open the authenticating pop-up.
++
+image::vscode-remote/login-with-provider.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/login-with-provider.png"]
+
+. Complete the authentication process.
++
+Paste in the code from the clipboard and follow the instructions.
+On successful authentication, close the pop-up and wait for the tunnel to your workspace to be created.
++
+image::vscode-remote/open-visual-studio-code.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/open-visual-studio-code.png"]
+
+. Open your workspace in Visual Studio Code desktop.
++
+Click *Open in Visual Studio Code desktop* to open your workspace in the desktop version of Visual Studio Code.
+Confirm opening the desktop application by clicking *Open Visual Studio Code - URL Handler*.
++
+image::vscode-remote/confirm-opening-vscode-desktop.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/confirm-opening-vscode-desktop.png"]
+
+[NOTE]
+====
+If you are not signed in yet, allow Visual Studio Code to sign in with the same account you used to create the tunnel.
+====
+
+[TIP]
+====
+If Visual Studio Code opens your workspace with a delay, open *Remote Explorer* view.
+====
+
+.Connecting Visual Studio Code to an existing workspace
+
+With link:https://code.visualstudio.com/docs/editor/command-line[Visual Studio Code Command Line Interface (CLI)] you can create a tunnel to an existing workspace.
+
+.Prerequisites
+
+. link:https://code.visualstudio.com/[Visual Studio Code] is installed.
+. link:https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server[Remote - Tunnels] extension is installed.
+
+.Procedure
+
+. Install Visual Studio Code CLI in your workspace.
++
+Open a terminal and run the following command to install Visual Studio Code CLI in the `/checode` directory.
++
+[source,shell,subs="attributes+"]
+----
+curl 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --location -o /tmp/code.tar.gz && \
+tar -xvzf /tmp/code.tar.gz --directory=/checode
+----
++
+[IMPORTANT]
+====
+If you don't have `gzip` installed in your workspace, you won't be able to install the CLI using the command above.
+In this case you need to:
+
+. link:https://code.visualstudio.com/Download[Download CLI] for *Linux x64* architecture to your desktop,
+unpack and upload the extracted binary to your workspace root.
+
+. Move CLI binary to `/checode` directory and make it executable:
+
+[source,shell,subs="attributes+"]
+----
+mv $PROJECT_SOURCE/code /checode && chmod +x /checode/code
+----
+
+====
+
+. Launch the Visual Studio Code CLI and log in using your Microsoft or GitHub account.
++
+[source,shell,subs="attributes+"]
+----
+/checode/code tunnel --accept-server-license-terms --name $DEVWORKSPACE_NAME
+----
++
+image::vscode-remote/cli-create-tunnel.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/cli-create-tunnel.png"]
++
+After successful login, you will be prompted to open the workspace in your browser.
+
+. Open your workspace in local Visual Studio Code.
++
+Open your local Visual Studio Code and navigate to *Remote Explorer* view. A tunnel to your workspace will appear.
+With the buttons on the right, open your workspace in the current or a new window.
++
+image::vscode-remote/vscode-remote-explorer.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/vscode-remote-explorer.png"]
+
+[NOTE]
+====
+A tunnel to your workspace will not appear if you are not signed in yet.
+Sign in using the same account you used to create the tunnel.
+====