Adding a Visual Studio Code extension to the Che plug-ins registry

To use a Visual Studio Code extension in a Che workspace, Che need to consume metadata describing the extension. The Che plug-ins registry is a static website publishing metadata for common Visual Studio Code extensions. Visual Studio Code extension metadata for the Che plug-ins registry is generated from a central file named che-theia-plugins.yaml.

To add or modify an extension in the Che plug-ins registry, edit the che-theia-plugins.yaml file and add relevant metadata.

This article describes the steps needed to build the plug-ins registry with a custom plug-in definition. If you are looking to create a custom meta.yaml file that can be directly referenced in a devfile, see Publishing metadata for a Visual Studio Code extension.

Prerequisite
  • A working knowledge of customizing the registries, see Customizing the registries

  • A link to a sidecar container image, should the Visual Studio Code extension require one.

Procedure
  1. Edit the che-theia-plugins.yaml file and create a new entry.

    - id: publisher/my-vscode-ext                                    (1)
      repository:                                                    (2)
        url: https://github.com/publisher/my-vscode-ext              (3)
        revision: 1.7.2                                              (4)
      aliases:                                                       (5)
        - publisher/my-vscode-ext-revised
      preferences:                                                   (6)
        asciidoc.use_asciidoctorpdf: true
        shellcheck.executablePath: /bin/shellcheck
        solargraph.bundlerPath: /usr/local/bin/bundle
        solargraph.commandPath: /usr/local/bundle/bin/solargraph
      sidecar:                                                       (7)
        image: quay.io/repository/eclipse/che-plugin-sidecar:sonarlint-2fcf341  (8)
        name: my-vscode-ext-sidecar                                  (9)
        memoryLimit: "1500Mi"                                        (10)
        memoryRequest: "1000Mi"                                      (11)
        cpuLimit: "500m"                                             (12)
        cpuRequest: "125m"                                           (13)
        command:                                                     (14)
            - /bin/sh
        args:                                                        (15)
            - "-c"
            - "./entrypoint.sh"
        volumeMounts:                                                (16)
          - name: vscode-ext-volume                                  (17)
            path: "/home/theia/my-vscode-ext"                        (18)
        endpoints:                                                   (19)
          - name: "configuration-endpoint"                           (20)
            public: true                                             (21)
            targetPort: 61436                                        (22)
            attributes:                                              (23)
              protocol: http
      extension: https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix    (24)
      skipDependencies:                                              (25)
        - id-of/extension1
        - id-of/extension2
      extraDependencies:                                             (26)
        - id-of/extension1
        - id-of/extension2
      metaYaml:
        skipIndex: <true|false>                                      (27)
        skipDependencies:                                            (28)
          - id-of/extension1
          - id-of/extension2
        extraDependencies:                                           (29)
          - id-of/extension1
          - id-of/extension2
1 (OPTIONAL) The ID of the plug-in, useful if a plug-in has multiple entries for one repository. For example, Java 8 and Java 11.
2 Repository information about the plug-in. If ID is specified, then this field is not a list element.
3 The URL to the Git repository of the extension.
4 Tag or SHA1 ID of the upstream repository that hosts the extension, corresponding to a version, snapshot, or release.
5 (OPTIONAL) An alias for this plug-in. For anything listed here, a meta.yaml file is generated.
6 (OPTIONAL) Plug-in preferences in freeform format.
7 (OPTIONAL) If the plug-in runs in a sidecar container, then the sidecar information is specified here.
8 A location of a container image to be used as the plug-in sidecar. This line cannot be specified concurrently with directory. See above.
9 (OPTIONAL) The name of the sidecar container.
10 (OPTIONAL) The memory limit of the sidecar container.
11 (OPTIONAL) The memory request of the sidecar container.
12 (OPTIONAL) The CPU limit of the sidecar container.
13 (OPTIONAL) The CPU request of the sidecar container.
14 (OPTIONAL) Definitions of root process commands inside the container.
15 (OPTIONAL) Arguments for root process commands inside the container.
16 (OPTIONAL) Any volume mounting information for the sidecar container.
17 The name of the mount.
18 The path to the mount.
19 (OPTIONAL) Any endpoint information for the sidecar container.
20 Endpoint name.
21 A Boolean value determining whether the endpoint is exposed publicly.
22 The port number.
23 Attributes relating to the endpoint.
24 Direct link or links to the vsix files included with the plug-in. The vsix built by the repository specified, such as the main extension, must be listed first.
25 # TODO #
26 (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json.
27 (OPTIONAL) Do not include this plug-in in index.json if true. Useful in case of dependencies that you do not want to expose as standalone plug-ins.
28 (OPTIONAL) Do not examine specified dependencies from extensionDependencies field of package.json (only for meta.yaml generation).
29 (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json (only for meta.yaml generation).
  1. Run the build.sh script with the options of your choosing. The build process will generate meta.yaml files automatically, based on the entries in the che-theia-plugins.yaml file.

  2. Use the resulting plug-ins registry image in Che, or copy the meta.yaml file out of the registry container and reference it directly as an HTTP resource.