Skip to content

Latest commit

 

History

History
336 lines (262 loc) · 13.6 KB

README.md

File metadata and controls

336 lines (262 loc) · 13.6 KB
Raw

semantic-release-vsce

semantic-release plugin to package and publish VS Code extensions.

npm downloads ci dependencies peerDependencies semantic-release

Step Description
verify Verify the package.json and the validity of the personal access tokens against Visual Studio Marketplace and/or Open VSX Registry when publish is enabled
prepare Generate the .vsix file using vsce (can be be controlled by the packageVsix config option
publish Publish the extension to Visual Studio Marketplace and/or Open VSX Registry (learn more here)

Install

npm install --save-dev semantic-release-vsce

or

yarn add --dev semantic-release-vsce

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-vsce",
      {
        "packageVsix": true
      }
    ],
    [
      "@semantic-release/github",
      {
        "assets": [
          {
            "path": "*.vsix"
          }
        ]
      }
    ]
  ]
}

Configuration

packageVsix

Whether to package or not the extension into a .vsix file, or where to place it. This controls if vsce package gets called or not, and what value will be used for vsce package --out.

Value Description
"auto" (default) behave as true in case publish is disabled or the OVSX_PAT environment variable is present
true package the extension .vsix, and place it at the current working directory
false disables packaging the extension .vsix entirely
a string package the extension .vsix and place it at the specified path

publish

Whether to publish or not the extension to Visual Studio Marketplace and/or to Open VSX Registry. This controls if vsce publish or ovsx publish gets called or not. Learn more here.

Value Description
true (default) publishes the extension to Visual Studio Marketplace and/or to Open VSX Registry
false disables publishing the extension to Visual Studio Marketplace and/or to Open VSX Registry

publishPackagePath

Which .vsix file (or files) to publish. This controls what value will be used for vsce publish --packagePath.

Value Description
"auto" (default) uses the .vsix packaged during the prepare step (if packaged), or behave as false otherwise
false do not use a .vsix file to publish, which causes vsce to package the extension as part of the publish process
a string publish the specified .vsix file(s). This can be a glob pattern, or a comma-separated list of files

packageRoot

The directory of the extension relative to the current working directory. Defaults to cwd.

Environment variables

The following environment variables are supported by this plugin:

Variable Description
OVSX_PAT Optional. The personal access token to push to Open VSX Registry
VSCE_PAT Optional. The personal access token to publish to Visual Studio Marketplace
VSCE_TARGET Optional. The target to use when packaging or publishing the extension (used as vsce package --target ${VSCE_TARGET}). When set to universal, behave as if VSCE_TARGET was not set (i.e. build the universal/generic vsix). See the platform-specific example

Configuring vsce

You can set vsce options in the package.json, like:

{
  "vsce": {
    "baseImagesUrl": "https://my.custom/base/images/url",
    "dependencies": true,
    "yarn": false
  }
}

For more information, check the vsce docs.

Publishing

This plugin can publish extensions to Visual Studio Marketplace and/or Open VSX Registry.

You can enable or disable publishing with the publish config option.

When publish is enabled (default), the plugin will publish to Visual Studio Marketplace if the VSCE_PAT environment variable is present, and/or to Open VSX Registry if the OVSX_PAT environment variable is present.

For example, you may want to disable publishing if you only want to publish the .vsix file as a GitHub release asset.

Publishing to Visual Studio Marketplace

Publishing extensions to Visual Studio Marketplace using this plugin is easy:

  1. Create your personal access token for Visual Studio Marketplace. Learn more here.

  2. Configure the VSCE_PAT environment variable in your CI with the token that you created.

  3. Enjoy! The plugin will automatically detect the environment variable and it will publish to Visual Studio Marketplace, no additional configuration is needed.

Publishing to Open VSX Registry

Publishing extensions to Open VSX Registry using this plugin is easy:

  1. Create your personal access token for Open VSX Registry. Learn more here.

  2. Configure the OVSX_PAT environment variable in your CI with the token that you created.

  3. Enjoy! The plugin will automatically detect the environment variable and it will publish to Open VSX Registry, no additional configuration is needed.

Examples

GitHub Actions

name: release

on:
  push:
    branches: [master]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # In case you want to publish to Visual Studio Marketplace
          VSCE_PAT: ${{ secrets.VSCE_PAT }}
          # In case you want to publish to Open VSX Registry
          OVSX_PAT: ${{ secrets.OVSX_PAT }}

Platform-specific on GitHub Actions

  1. Install semantic-release-stop-before-publish

    npm install --save-dev semantic-release-stop-before-publish

    We will use it to make semantic-release stop before publishing anything, so that we can use semantic-release to build each .vsix in a matrix.

  2. Separate your semantic-release configuration into two, one for packaging and another for publishing.

    The one for packaging has semantic-release-stop-before-publish so that semantic-release does not publish anything (which includes the git tag).

    // package.release.config.js
module.exports = {
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    [
      'semantic-release-vsce',
      {
        packageVsix: true,
        publish: false, // no-op since we use semantic-release-stop-before-publish
      },
    ],
    'semantic-release-stop-before-publish',
  ],
};

    The one for publishing does not package the .vsix, but publishes all the *.vsix files.

    // publish.release.config.js
module.exports = {
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    [
      'semantic-release-vsce',
      {
        packageVsix: false,
        publishPackagePath: '*/*.vsix',
      },
    ],
    [
      '@semantic-release/github',
      {
        assets: '*/*.vsix',
      },
    ],
  ],
};

    Note: do not forget to remove your existing semantic-release configuration.

  3. Create a workflow file like below:

# .github/workflows/ci.yaml
name: ci

on:
  push:
    branches: [master]

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: windows-latest
            target: win32-x64
            npm_config_arch: x64
          - os: windows-latest
            target: win32-arm64
            npm_config_arch: arm
          - os: ubuntu-latest
            target: linux-x64
            npm_config_arch: x64
          - os: ubuntu-latest
            target: linux-arm64
            npm_config_arch: arm64
          - os: ubuntu-latest
            target: linux-armhf
            npm_config_arch: arm
          - os: ubuntu-latest
            target: alpine-x64
            npm_config_arch: x64
          - os: macos-latest
            target: darwin-x64
            npm_config_arch: x64
          - os: macos-latest
            target: darwin-arm64
            npm_config_arch: arm64
          - os: ubuntu-latest
            target: universal
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: 16

      - if: matrix.target != 'universal'
        name: Install dependencies (with binaries)
        run: npm ci
        env:
          npm_config_arch: ${{ matrix.npm_config_arch }}

      - if: matrix.target == 'universal'
        name: Install dependencies (without binaries)
        run: npm ci

      - run: npx semantic-release --extends ./package.release.config.js
        env:
          VSCE_TARGET: ${{ matrix.target }}
          # All tokens are required since semantic-release needs to validate them
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # In case you want to publish to Visual Studio Marketplace
          VSCE_PAT: ${{ secrets.VSCE_PAT }}
          # In case you want to publish to Open VSX Registry
          OVSX_PAT: ${{ secrets.OVSX_PAT }}

      - uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.target }}
          path: '*.vsix'

  release:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: 16

      - run: npm ci

      - uses: actions/download-artifact@v3

      - run: npx semantic-release --extends ./publish.release.config.js
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # In case you want to publish to Visual Studio Marketplace
          VSCE_PAT: ${{ secrets.VSCE_PAT }}
          # In case you want to publish to Open VSX Registry
          OVSX_PAT: ${{ secrets.OVSX_PAT }}

A reference implementation can also be found in the VS Code ShellCheck extension.