Publish Extensions to Open VSX

A CI script for publishing open-source VS Code extensions to open-vsx.org.

When to Add an Extension?

A goal of Open VSX is to have extension maintainers publish their extensions according to the documentation. The first step we recommend is to open an issue with the extension owner. If the extension owner is unresponsive for some time, this repo (publish-extensions) can be used as a temporary workaround to esure the extension is published to Open VSX.

In the long-run it is better for extension owners to publish their own plugins because:

1. Any future issues (features/bugs) with any published extensions in Open VSX will be directed to their original repo/source-control, and not confused with this repo publish-extensions.
2. Extensions published by official authors are shown within the Open VSX marketplace as such. Whereas extensions published via publish-extensions display a warning that the publisher (this repository) is not the official author.
3. Extension owners who publish their own extensions get greater flexibility on the publishing/release process, therefore ensure more accuracy/stability. For instance, in some cases publish-extensions has build steps within this repository, which can cause some uploaded plugin versions to break (e.g. if a plugin build step changes).

⚠️ We accept only extensions with OSI-approved open source licenses here. If you want to have an extension with a proprietary or non-approved license, please ask its maintainers to publish it.

How to Add an Extension?

To automatically publish an extension to Open VSX, simply add it to extensions.json with the options described below. You can run node add-extension [REPOSITORY] --checkout to create an entry automatically.

⚠️ Some extensions require additional build steps, and failing to execute them may lead to a broken extension published to Open VSX. Please check the extension's scripts section in the package.json file to find such steps; usually they are named build or similar. In case the build steps are included in the vscode:prepublish script, they are executed automatically, so it's not necessary to mention them explicitly. Otherwise, please include them in the prepublish value, e.g. "prepublish": "npm run build".

Click the button below to start a Gitpod workspace where you can run the scripts contained in this repository:

Publishing Options

The best way to add an extension here is to open this repository in Gitpod (using the orange button above) and to run this helper script:

node add-extension $REPOSITORY_URL --checkout

Notes:

• Simply replace $REPOSITORY_URL with the extension's actual repository URL
• This will update extensions.json automatically, which you can commit to send a Pull Request
• Adding --checkout (without an explicit value) will auto-detect the latest available Git release tag or branch

If you're curious, here are the expected formats of an extensions.json entry:

    {
      // Unique Open VSX extension ID in the form "<namespace>.<name>"
      "id": "rebornix.ruby",
      // A full URL from which to download the extension package
      "download": "https://github.com/rubyide/vscode-ruby/releases/download/v0.25.0/ruby-0.25.0.vsix",
      // (RECOMMENDED) The version that should be published; the script compares this version with the latest published version
      "version": "0.25.0"
    },

Or, in cases where the extension maintainers don't provide a .vsix release to download, you can build the extension from source instead:

    {
      // Unique Open VSX extension ID in the form "<namespace>.<name>"
      "id": "redhat.vscode-yaml",
      // Repository URL to clone and publish from
      "repository": "https://github.com/redhat-developer/vscode-yaml"
    },

Here are all the supported values, including optional ones, to build extensions from source:

    {
      // Unique Open VSX extension ID in the form "<namespace>.<name>"
      "id": "rebornix.ruby",
      // Repository URL to clone and publish from
      "repository": "https://github.com/rubyide/vscode-ruby",
      // (RECOMMENDED) The version that should be published; the script compares this version with the latest published version
      "version": "0.27.0",
      // (RECOMMENDED) The Git branch, tag, or commit to check out before publishing (defaults to the repository's default branch)
      "checkout": "v0.27.0",
      // (OPTIONAL) Location of the extension's package.json in the repository (defaults to the repository's root directory)
      "location": "packages/vscode-ruby-client",
      // (OPTIONAL) Extra commands to run just before publishing to Open VSX (i.e. after "yarn/npm install", but before "vscode:prepublish")
      "prepublish": "npm run build",
      // (OPTIONAL) Relative path of the extension vsix file inside the git repo (i.e. when it is built by prepublish commands
      "extensionFile": "dist/js-debug.vsix",
      // (OPTIONAL) Enables publishing of web extensions.
      "web": true
    },

How do extensions get updated?

Every week a job is ran which checks for updated versions. These changes are reviewed manually, and merged by a maintainer. Once merged, these upgrades are published nightly. There should be no reason to raise a PR to update an extension. It could be that the extension is failing to update.

To debug, try running node upgrade-extensions.js --extension=the-extension-id, which will try to run the upgrade only for that one extension, providing an error report/reason for why the extension is not updating.

How are Extensions Published?

Every night at 03:03 UTC, a GitHub workflow goes through all entries in extensions.json, and checks if the specified "version" needs to be published to https://open-vsx.org or not.

The publishing process can be summarized like this:

1. git clone "repository"
2. (git checkout "checkout" if a "checkout" value is specified)
3. npm install (or yarn install if a yarn.lock file is detected in the repository)
4. ("prepublish")
5. (ovsx create-namespace "publisher" if it doesn't already exist)
6. ovsx publish (with --yarn if a yarn.lock file was detected earlier)

See all ovsx CLI options here.