Chapter 6. Configuring Visual Studio Code - Open Source ("Code - OSS") Learn how to configure Visual Studio Code - Open Source ("Code - OSS"). Section 6.1, "Configuring single and multiroot workspaces" Section 6.2, "Configure trusted extensions for Microsoft Visual Studio Code" Section 6.3, "Configure default extensions" Section 6.4, "Applying editor configurations" 6.1. Configuring single and multiroot workspaces With the multi-root workspace feature, you can work with multiple project folders in the same workspace. This is useful when you are working on several related projects at once, such as product documentation and product code repositories. Tip See What is a VS Code "workspace" for better understanding and authoring the workspace files. Note The workspace is set to open in multi-root mode by default. Once workspace is started, the /projects/.code-workspace workspace file is generated. The workspace file will contain all the projects described in the devfile. { "folders": [ { "name": "project-1", "path": "/projects/project-1" }, { "name": "project-2", "path": "/projects/project-2" } ] } If the workspace file already exist, it will be updated and all missing projects will be taken from the devfile. If you remove a project from the devfile, it will be left in the workspace file. You can change the default behavior and provide your own workspace file or switch to a single-root workspace. Procedure Provide your own workspace file. Put a workspace file with the name .code-workspace into the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") will use the workspace file as it is. { "folders": [ { "name": "project-name", "path": "." } ] } Important Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") will be opened instead. Important If you have several projects, the workspace file will be taken from the first project. If the workspace file does not exist in the first project, a new one will be created and placed in the /projects directory. Specify alternative workspace file. Define the VSCODE_DEFAULT_WORKSPACE environment variable in your devfile and specify the right location to the workspace file. env: - name: VSCODE_DEFAULT_WORKSPACE value: "/projects/project-name/workspace-file" Open a workspace in a single-root mode. Define VSCODE_DEFAULT_WORKSPACE environment variable and set it to the root. env: - name: VSCODE_DEFAULT_WORKSPACE value: "/" 6.2. Configure trusted extensions for Microsoft Visual Studio Code You can use the trustedExtensionAuthAccess field in the product.json file of Microsoft Visual Studio Code to specify which extensions are trusted to access authentication tokens. "trustedExtensionAuthAccess": [ "<publisher1>.<extension1>", "<publisher2>.<extension2>" ] This is particularly useful when you have extensions that require access to services such as GitHub, Microsoft, or any other service that requires OAuth. By adding the extension IDs to this field, you are granting them the permission to access these tokens. You can define the variable in the devfile or in the ConfigMap. Pick the option that better suits your needs. With a ConfigMap, the variable will be propagated on all your workspaces and you do not need to add the variable to each the devfile you are using. Warning Use the trustedExtensionAuthAccess field with caution as it could potentially lead to security risks if misused. Give access only to trusted extensions. Procedure Since the Microsoft Visual Studio Code editor is bundled within che-code image, you can only change the product.json file when the workspace is started up. Define the VSCODE_TRUSTED_EXTENSIONS environment variable. Choose between defining the variable in devfile.yaml or mounting a ConfigMap with the variable instead. Define the VSCODE_TRUSTED_EXTENSIONS environment variable in devfile.yaml: env: - name: VSCODE_TRUSTED_EXTENSIONS value: "<publisher1>.<extension1>,<publisher2>.<extension2>" Mount a ConfigMap with VSCODE_TRUSTED_EXTENSIONS environment variable: kind: ConfigMap apiVersion: v1 metadata: name: trusted-extensions labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-configmap: 'true' annotations: controller.devfile.io/mount-as: env data: VSCODE_TRUSTED_EXTENSIONS: '<publisher1>.<extension1>,<publisher2>.<extension2>' Verification The value of the variable will be parsed on the workspace startup and the corresponding trustedExtensionAuthAccess section will be added to the product.json . 6.3. Configure default extensions Default extensions are a pre-installed set of extensions, specified by putting the extension binary .vsix file path to the DEFAULT_EXTENSIONS environment variable. After startup, the editor checks for this environment variable, and if it is specified, takes the path to the extensions and installs it in the background without disturbing the user. Configuring default extensions is useful for installing .vsix extensions from the editor level. Note If you want to specify multiple extensions, separate them by semicolon. DEFAULT_EXTENSIONS='/projects/extension-1.vsix;/projects/extension-2.vsix' Read on to learn how to define the DEFAULT_EXTENSIONS environment variable, including multiple examples of adding .vsix files to your workspace. There are three different ways to embed default .vsix extensions into your workspace: Put the extension binary into the source repository. Use the devfile postStart event to fetch extension binaries from the network. Include the extensions' .vsix binaries in the che-code image. Putting the extension binary into the source repository Putting the extension binary into the Git repository and defining the environment variable in the devfile is the easiest way to add default extensions to your workspace. If the extension.vsix file exists in the repository root, you can set the DEFAULT_EXTENSIONS for a tooling container. Procedure Specify DEFAULT_EXTENSIONS in your .devfile.yaml as shown in the following example: schemaVersion: 2.3.0 metadata: generateName: example-project components: - name: tools container: image: quay.io/devfile/universal-developer-image:ubi8-latest env: - name: 'DEFAULT_EXTENSIONS' value: '/projects/example-project/extension.vsix' Using the devfile postStart event to fetch extension binaries from the network You can use cURL or GNU Wget to download extensions to your workspace. For that you need to: specify a devfile command to download extensions to your workpace add a postStart event to run the command on workspace startup define the DEFAULT_EXTENSIONS environment variable in the devfile Procedure Add the values shown in the following example to the devfile: schemaVersion: 2.3.0 metadata: generateName: example-project components: - name: tools container: image: quay.io/devfile/universal-developer-image:ubi8-latest env: - name: DEFAULT_EXTENSIONS value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix' commands: - id: add-default-extensions exec: # name of the tooling container component: tools # download several extensions using curl commandLine: | curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix events: postStart: - add-default-extensions Warning In some cases curl may download a .gzip compressed file. This might make installing the extension impossible. To fix that try to save the file as a .vsix.gz file and then decompress it with gunzip . This will replace the .vsix.gz file with an unpacked .vsix file. curl https://some-extension-url --location -o /tmp/extension.vsix.gz gunzip /tmp/extension.vsix.gz Including the extensions .vsix binaries in the che-code image. With default extensions bundled in the editor image, and the DEFAULT_EXTENSIONS environment variable defined in the ConfigMap, you can apply the default extensions without changing the devfile. Following the steps below to add the extensions you need to the editor image. Procedure Create a directory and place your selected .vsix extensions in this directory. Create a Dockerfile with the following content: Build the image and then push it to a registry: Add the new ConfigMap to the user's project, define the DEFAULT_EXTENSIONS environment variable, and specify the absolute paths to the extensions. This ConfigMap sets the environment variable to all workspaces in the user's project. kind: ConfigMap apiVersion: v1 metadata: name: vscode-default-extensions labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-configmap: 'true' annotations: controller.devfile.io/mount-as: env data: DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix' Create a workspace using yourname/che-code: image. First, open the dashboard and navigate to the Create Workspace tab on the left side. In the Editor Selector section, expand the Use an Editor Definition dropdown and set the editor URI to the Editor Image . Create a workspace by clicking on any sample or by using a Git repository URL. 6.4. Applying editor configurations You can configure Visual Studio Code - Open Source editor by adding configurations to a ConfigMap. These configurations are applied to any workspace you open. Once a workspace is started, the editor checks for this ConfigMap and stores configurations to the corresponding config files. The following sections are currently supported: settings.json extensions.json The settings.json section contains various settings that allow to customize different parts of the Code - OSS editor. The extensions.json section contains recommented extensions are installed when a workspace is started. Procedure Add a new ConfigMap to the user's project, define the settings.json and extensions.json sections, specify the settings you want to add, and the IDs of the extensions you want to install. apiVersion: v1 kind: ConfigMap metadata: name: vscode-editor-configurations data: extensions.json: | { "recommendations": [ "dbaeumer.vscode-eslint", "github.vscode-pull-request-github" ] } settings.json: | { "window.header": "A HEADER MESSAGE", "window.commandCenter": false, "workbench.colorCustomizations": { "titleBar.activeBackground": "#CCA700", "titleBar.activeForeground": "#ffffff" } } immutable: false Start or restart your workspace Note Make sure that the Configmap contains data in a valid JSON format. Verification Verify that settings defined in the ConfigMap are applied using one of the following methods: Use F1 Preferences: Open Remote Settings to check if the defined settings are applied. Ensure that the settings from the ConfigMap are present in the /checode/remote/data/Machine/settings.json file by using the F1 File: Open File... command to inspect the file's content. Verify that extensions defined in the ConfigMap are applied: Go to the Extensions view ( F1 View: Show Extensions ) and check that the extensions are installed Ensure that the extensions from the ConfigMap are present in the .code-workspace file by using the F1 File: Open File... command. By default, the workspace file is placed at /projects/.code-workspace .

Commands:
{ "folders": [ { "name": "project-1", "path": "/projects/project-1" }, { "name": "project-2", "path": "/projects/project-2" } ] }
{ "folders": [ { "name": "project-name", "path": "." } ] }
env: - name: VSCODE_DEFAULT_WORKSPACE value: "/projects/project-name/workspace-file"
env: - name: VSCODE_DEFAULT_WORKSPACE value: "/"
"trustedExtensionAuthAccess": [ "<publisher1>.<extension1>", "<publisher2>.<extension2>" ]
env: - name: VSCODE_TRUSTED_EXTENSIONS value: "<publisher1>.<extension1>,<publisher2>.<extension2>"
kind: ConfigMap apiVersion: v1 metadata: name: trusted-extensions labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-configmap: 'true' annotations: controller.devfile.io/mount-as: env data: VSCODE_TRUSTED_EXTENSIONS: '<publisher1>.<extension1>,<publisher2>.<extension2>'
DEFAULT_EXTENSIONS='/projects/extension-1.vsix;/projects/extension-2.vsix'
schemaVersion: 2.3.0 metadata: generateName: example-project components: - name: tools container: image: quay.io/devfile/universal-developer-image:ubi8-latest env: - name: 'DEFAULT_EXTENSIONS' value: '/projects/example-project/extension.vsix'
schemaVersion: 2.3.0 metadata: generateName: example-project components: - name: tools container: image: quay.io/devfile/universal-developer-image:ubi8-latest env: - name: DEFAULT_EXTENSIONS value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix' commands: - id: add-default-extensions exec: # name of the tooling container component: tools # download several extensions using curl commandLine: | curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix events: postStart: - add-default-extensions
curl https://some-extension-url --location -o /tmp/extension.vsix.gz gunzip /tmp/extension.vsix.gz
inherit che-incubator/che-code:latest FROM quay.io/che-incubator/che-code:latest USER 0 copy all .vsix files to /default-extensions directory RUN mkdir --mode=775 /default-extensions COPY --chmod=755 *.vsix /default-extensions/ add instruction to the script to copy default extensions to the working container RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh
docker build -t yourname/che-code:next . docker push yourname/che-code:next
kind: ConfigMap apiVersion: v1 metadata: name: vscode-default-extensions labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-configmap: 'true' annotations: controller.devfile.io/mount-as: env data: DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix'
apiVersion: v1 kind: ConfigMap metadata: name: vscode-editor-configurations data: extensions.json: | { "recommendations": [ "dbaeumer.vscode-eslint", "github.vscode-pull-request-github" ] } settings.json: | { "window.header": "A HEADER MESSAGE", "window.commandCenter": false, "workbench.colorCustomizations": { "titleBar.activeBackground": "#CCA700", "titleBar.activeForeground": "#ffffff" } } immutable: false