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
+
+The following steps will help you to connect your 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)` 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"]
++
+
+. Proceed the login using your Microsoft or GitHub account.
++
+Click `Copy & Continue to Microsoft` or `Copy & Continue to GitHub` button in the appeared dialog to copy the authentication code to the clipboard and open the authenticating pop-up.
++
+image::vscode-remote/login-with-provider.png[Open Gateway prompt,link="{imagesdir}/vscode-remote/login-with-provider.png"]
+
+. Complete authenticating.
++
+In the appeared pop-up you can paste the code from the clipboard and follow the instructions.
+On successful authentication, close the pop-up and wait while a tunnel to your workspace will 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 your desktop Visual Studio Code.
+In the appeared pop-up click `Open Visual Studio Code - URL Handler` to confirm opening the desktop application.
++
+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 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 crate 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 to your workspace.
++
+Open a terminal and run the following command to install Visual Studio Code CLI to `/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 to your workspace, you won't be able to install the CLI using the above command.
+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 in executable
+
+[source,shell,subs="attributes+"]
+----
+mv $PROJECT_SOURCE/code /checode && chmod +x /checode/code
+----
+
+====
+
+. Launch CLI and login 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 new tunnel to your workspace should appear.
+With buttons on the right, open your workspace in a current or in 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.
+If so happened, sign in using the account you are used to create a tunnel.
+====