How the Open VSX extension registry works

To manage extensions, Che uses one of the following Open VSX registry instances:

The embedded instance of the Open VSX registry that runs in the plugin-registry pod of Che to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on open-vsx.org. You can customize this subset using a workspace or using a Linux operating system.
The public open-vsx.org registry that is accessed over the internet.
A standalone Open VSX registry instance that is deployed on a network accessible from Che workspace pods.
An Operator-managed Open VSX registry deployed as a Che operand. See Enable the managed Open VSX registry.

The default is the Open VSX registry at https://open-vsx.org.

Choose which registry to use

The default is the Open VSX registry at https://open-vsx.org.

If the default Open VSX registry instance does not meet your requirements, you can select one of the following instances:

The embedded instance of the Open VSX registry that runs in the plugin-registry pod of Che to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on open-vsx.org. You can customize this subset using a workspace or using a Linux operating system.
A standalone Open VSX registry instance that is deployed on a network accessible from Che workspace pods.

Prerequisites

You have administrator access to the cluster where Che is deployed.
You have the oc CLI tool installed if you are using the command line.

Procedure

Log in to the cluster as an administrator.
Edit the CheCluster custom resource to update the openVSXURL value:
```
spec:
  components:
    pluginRegistry:
      openVSXURL: "<url_of_an_open_vsx_registry_instance>" (1)
```
1 For example: openVSXURL: "https://open-vsx.org".

Save the changes to the custom resource.

Do not use https://open-vsx.org in an air-gapped environment or an environment that is isolated from the internet. To reduce the risk of malware infections and unauthorized access to your code, use the embedded or a self-hosted Open VSX registry with a curated set of extensions.
To select the embedded Open VSX registry instance in the plugin-registry pod, use openVSXURL: ''. You can customize the list of included extensions using a workspace or using a Linux operating system.
You can point openVSXURL to the URL of a standalone Open VSX registry instance if the URL is accessible from within the organization’s cluster and not blocked by a proxy.

Verification

Confirm that the plugin-registry pod has restarted.
Open a workspace and verify that extensions are available from the selected registry instance in the Extensions view.

Add or remove extensions in a workspace

You can add or remove extensions in the embedded Open VSX registry instance directly within a Che workspace to create a custom build for your organization.

The embedded plugin registry is deprecated. Setting up an internal, on-premises Open VSX registry provides full control over the extension lifecycle, enables offline use, and improves compliance. Refer to the Build the extension registry from source procedure for detailed setup instructions.

Prerequisites

You have started a workspace using the plugin registry repository.
You are logged in to the cluster as a cluster administrator from the workspace terminal: $ oc login --token=<USER_TOKEN> --server=<CLUSTER_API_URL>
You have created a Red Hat Registry Service Account and have the username and token available.
For IBM Power (ppc64le) and IBM Z (s390x) architectures, you must build the custom plugin registry locally on the corresponding hardware.
(Optional) You can rebuild the container based on the latest tag or SHA to get the latest security fixes after a Che update.

Procedure

Identify the publisher and extension name for each extension you want to add:

Find the extension on the Open VSX registry website.
Copy the URL of the extension’s listing page.

Extract the <publisher> and <name> from the URL:

https://open-vsx.org/extension/<publisher>/<name>

If the extension is only available from Microsoft Visual Studio Marketplace, but not Open VSX, you can ask the extension publisher to publish it on open-vsx.org according to these instructions, potentially using this GitHub action.

If the extension publisher is unavailable or unwilling to publish the extension to open-vsx.org, and if there is no Open VSX equivalent of the extension, consider reporting an issue to the Open VSX team.

Open the openvsx-sync.json file in the workspace.

Add or remove extensions using the following JSON syntax:

{
    "id": "<publisher>.<name>",
    "version": "<extension_version>"
}

If you have a closed-source extension or an extension developed only for internal use in your organization, you can add the extension directly from a .vsix file by using a URL accessible to your custom plugin registry container:

{
    "id": "<publisher>.<name>",
    "download": "<url_to_download_vsix_file>",
    "version": "<extension_version>"
}

Read the Terms of Use for the Microsoft Visual Studio Marketplace before using its resources.

Log in to the Red Hat registry:
1. Navigate to Terminal → Run Task… → devfile.
2. Run the 1. Login to registry.redhat.io task.
3. Enter your Red Hat Registry Service Account credentials when prompted.
Build and publish the custom plugin registry:
1. Navigate to Terminal → Run Task… → devfile.
2. Run the 2. Build and Publish a Custom Plugin Registry task.
  
  Verify that the CHE_CODE_VERSION in the build-config.json file matches the version of the editor currently used with Che. Update it if necessary.
Configure Che to use the custom plugin registry:
1. Navigate to Terminal → Run Task… → devfile.
2. Run the 3. Configure Che to use the Custom Plugin Registry task.

Verification

Check that the plugin-registry pod has restarted and is running.
Restart your workspace.
Open the Extensions view in the IDE and verify that your added extensions are available.

Additional resources

Add or remove extensions from the command line

You can build and publish a custom plugin registry using the Linux command line. This results in a custom build of the Open VSX registry that can be used in your organization’s workspaces.

Prerequisites

Podman is installed.
Node.js version 18.20.3 or higher is installed.
You have created a Red Hat Registry Service Account and have the username and token available.
You have read the Terms of Use for the Microsoft Visual Studio Marketplace before using its resources.
(Optional) You can rebuild the container based on the latest tag or SHA to get the latest security fixes after a Che update.

Procedure

Clone the plugin registry repository:

$ git clone https://github.com/redhat-developer/che-plugin-registry.git

Change to the plugin registry directory:
```
$ cd che-plugin-registry
```
Log in to the Red Hat registry:
```
$ podman login registry.redhat.io
```

Identify the publisher and extension name for each extension you want to add:

Find the extension on the Open VSX registry website.
Copy the URL of the extension’s listing page.

Extract the <publisher> and <name> from the URL:

https://open-vsx.org/extension/<publisher>/<name>

Open the openvsx-sync.json file.

Add or remove extensions using the following JSON syntax:

{
    "id": "<publisher>.<name>",
    "version": "<extension_version>"
}

{
    "id": "<publisher>.<name>",
    "download": "<url_to_download_vsix_file>",
    "version": "<extension_version>"
}

Build the plugin registry container image:
```
$ ./build.sh -o <username> -r quay.io -t custom
```
Verify that the CHE_CODE_VERSION in the build-config.json file matches the version of the editor currently used with Che. Update it if necessary.

Push the image to a container registry such as quay.io:

$ podman push quay.io/<username>/plugin_registry:custom

Edit the CheCluster custom resource in your organization’s cluster to point to the image and save the changes:

spec:
  components:
    pluginRegistry:
      deployment:
        containers:
          - image: quay.io/<username>/plugin_registry:custom
      openVSXURL: ''

Verification

Check that the plugin-registry pod has restarted and is running.
Restart your workspace.
Open the Extensions view in the IDE and verify that your added extensions are available.

Additional resources