semantic-release-vsce

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


| 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

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

or

`console
yarn add --dev semantic-release-vsce
`

Usage

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

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

Configuration

$3

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 |

$3

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 |

$3

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 |

$3

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

$3

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. _Note:_ Cannot be set at the same time as VSCE_AZURE_CREDENTIAL. |
| VSCE_AZURE_CREDENTIAL | _Optional_. When set to true or 1, vsce will use the --azure-credential flag to authenticate. _Note:_ Cannot be set at the same time as VSCE_PAT. |
| 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 |

$3

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

`json
{
"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.

$3

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.

$3

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

$3

`yaml
name: release

on:
push:
branches:
- master

permissions:
contents: read # for checkout

jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- 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 }}
`

$3

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

`console
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).

`js
// package.release.config.js
/**
* @type {import('semantic-release').GlobalConfig}
*/
export default {
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
[
'semantic-release-vsce',
{
packageVsix: true,
publish: false,
},
],
'semantic-release-stop-before-publish',
],
};
`

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

`js
// publish.release.config.js
/**
* @type {import('semantic-release').GlobalConfig}
*/
export default {
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:

`yaml


.github/workflows/ci.yaml

release:
runs-on: ubuntu-latest
needs: build
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
with:
merge-multiple: true
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- 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 }}
`

$3

`yaml
name: release

on:
push:
branches:
- master

permissions:
contents: read # for checkout

jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
VSCE_AZURE_CREDENTIAL: 'true'
``

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