How the Open VSX extension registry works

Che uses an Open VSX registry instance to manage extensions for Microsoft Visual Studio Code - Open Source.

To manage extensions, this IDE uses one of the 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 the public open-vsx.org registry. This subset is customizable.

  • 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.

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 Kubernetes cluster where Che is deployed.

  • You have an active kubectl session with administrative permissions. See Overview of kubectl.

Procedure

  1. 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".

  2. 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

  1. Confirm that the plugin-registry pod has restarted.

  2. 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

Customize the embedded Open VSX registry instance by adding or removing extensions directly within a Che workspace to create a custom extension catalog for your organization.

The embedded plugin registry is deprecated; the Open VSX Registry is its successor. Setting up an internal, on-premises Open VSX Registry provides full control over the extension lifecycle, enables offline use, and improves compliance. See Build a custom extension registry from source for detailed setup instructions.
Prerequisites

  • You are logged in to the Kubernetes cluster from the workspace terminal with cluster administrator permissions:

    kubectl login --token=<token> --server=<api_server_url>

  • You have started a workspace using the plugin registry repository.

  • You have created a Red Hat Registry Service Account and have the username and token available.

  • You have the custom plugin registry built locally on the corresponding hardware for IBM Power (ppc64le) and IBM Z (s390x) architectures.

  • You have a container image based on the latest tag or SHA to include the latest security fixes.

Procedure

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

    1. Find the extension on the Open VSX registry website.

    2. Copy the URL of the extension’s listing page.

    3. 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 and not Open VSX, ask the extension publisher to publish it on open-vsx.org. See the publishing instructions and the GitHub action.

      If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, consider reporting an issue to the Open VSX team.

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

  3. Add or remove extensions using the following JSON syntax:

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

    If you have a closed-source or internal-only extension, you can add it directly from a .vsix file. Use 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.

  4. 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.

  5. 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.

  6. 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

  1. Check that the plugin-registry pod has restarted and is running.

  2. Restart your workspace.

  3. Open the Extensions view in the IDE and verify that your added extensions are available.

Additional resources

Add or remove extensions from the Linux command line

Build and publish a custom plugin registry from the Linux command line to create a tailored Open VSX registry with the specific extensions your organization needs.

Prerequisites

  • You have docker installed.

  • You have Node.js version 18.20.3 or higher installed.

  • You have created a Red Hat Registry Service Account and have the username and token available.

  • You have a container image based on the latest tag or SHA to include the latest security fixes.

Procedure

  1. Clone the plugin registry repository:

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

  2. Change to the plugin registry directory:

    $ cd che-plugin-registry/

  3. Log in to the Red Hat registry:

    $ docker login registry.redhat.io

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

    1. Find the extension on the Open VSX registry website.

    2. Copy the URL of the extension’s listing page.

    3. 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 and not Open VSX, ask the extension publisher to publish it on open-vsx.org. See the publishing instructions and the GitHub action.

      If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, consider reporting an issue to the Open VSX team.

  5. Open the openvsx-sync.json file.

  6. Add or remove extensions using the following JSON syntax:

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

    If you have a closed-source or internal-only extension, you can add it directly from a .vsix file. Use 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.

  7. 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.

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

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

  9. 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

  1. Check that the plugin-registry pod has restarted and is running.

  2. Restart your workspace.

  3. Open the Extensions view in the IDE and verify that your added extensions are available.

Additional resources