> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unhook.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# VSCode Extension Release Automation

> Automated release system for the VSCode extension

# VSCode Extension Release Automation

This document outlines the automated release system for the VSCode extension (`apps/vscode-extension`) that enables seamless publishing to both the Visual Studio Marketplace and Open VSX Registry.

## Implementation Overview

The automation consists of two main components:

### 1. GitHub Workflow

The workflow is defined in `.github/workflows/vscode-extension-release.yml`:

**Triggers:**

* Automatically after the "NPM Release" workflow completes
* Manual dispatch for testing/emergency releases

**Conditions:**

* Only runs when the commit message contains "chore: version packages" (indicating a version bump)
* Only runs when the VSCode extension's `package.json` version was actually changed

**Process:**

1. **Version Check**: Validates that this is a version bump commit and that the VSCode extension version specifically changed
2. **Release**: Builds, packages, publishes to both marketplaces, and creates GitHub release

### 2. Composite Action

The composite action is located at `tooling/github/vscode-extension/github-release/action.yml`:

**Steps:**

1. **Setup Environment**: Uses the shared setup action
2. **Build Extension**: Runs `bun run build` to compile the extension
3. **Package Extension**: Creates VSIX file using `bunx vsce package`
4. **Publish to Visual Studio Marketplace**: Publishes using `bunx vsce publish`
5. **Publish to Open VSX Registry**: Publishes using `bunx ovsx publish`
6. **Extract Changelog**: Reads version-specific changes from `CHANGELOG.md`
7. **Create GitHub Release**: Creates release with tag `vscode-v{version}` and attaches VSIX file

## Setup Requirements

### Required GitHub Secrets

Add the following secrets to your GitHub repository:

* `VSCE_PAT`: Personal Access Token for Visual Studio Marketplace
  * Generate at: [https://dev.azure.com/](https://dev.azure.com/)
  * Requires "Marketplace (publish)" scope
  * Should be associated with the publisher account ("unhook")

* `OVSX_PAT`: Personal Access Token for Open VSX Registry
  * Generate at: [https://open-vsx.org/user-settings/tokens](https://open-vsx.org/user-settings/tokens)
  * Requires publishing permissions
  * Should be associated with your Open VSX account

### Open VSX Registry Setup

Before publishing to Open VSX, you need to:

1. **Create an Eclipse account** at eclipse.org (use same GitHub account as open-vsx.org)
2. **Sign the Publisher Agreement** at open-vsx.org
3. **Create an access token** in your Open VSX settings
4. **Namespace creation** is handled automatically by the workflow

<Note>
  The automation will automatically create the namespace (publisher) if it doesn't exist during the first publish.
</Note>

### VSCode Extension Configuration

The automation expects:

* Extension built with Bun (already configured)
* Extension publisher set to "unhook" in `package.json` (already set)
* Changelog maintained in `apps/vscode-extension/CHANGELOG.md` with version sections like:

```markdown theme={null}
## 0.0.3
- Feature description
- Bug fix description

## 0.0.2
- Previous version changes
```

## Workflow Integration

### Automatic Process

1. **NPM Release**: Maintainer triggers NPM Release workflow (manually or via GitHub Actions)
2. **Version Bump**: Release script bumps versions and generates AI-powered changelog
3. **VSCode Release**: If VSCode extension version changed, the VSCode Extension Release workflow automatically triggers
4. **Dual Marketplace Publication**: Extension is built, packaged, and published to both Visual Studio Marketplace and Open VSX Registry
5. **GitHub Release**: Release created with VSIX file attachment

### Manual Fallback

If automation fails, manual release steps:

```bash theme={null}
# Navigate to extension directory
cd apps/vscode-extension

# Build extension
bun run build

# Package extension
bun run vsce

# Publish to Visual Studio Marketplace
bunx vsce publish

# Publish to Open VSX Registry (requires OVSX_PAT environment variable)
bun run ovsx
```

## Marketplace Coverage

Publishing to both marketplaces ensures broad compatibility:

* **Visual Studio Marketplace**: Used by Microsoft VS Code
* **Open VSX Registry**: Used by VS Code alternatives like:
  * VSCodium
  * Gitpod
  * Eclipse Theia
  * Code-OSS distributions

## Monitoring

The workflow provides clear logging for each step:

* Build status and output
* Package creation
* Visual Studio Marketplace publishing result
* Open VSX Registry publishing result
* GitHub release creation

Failed steps will be clearly indicated in the GitHub Actions logs.

## Security Considerations

* Both `VSCE_PAT` and `OVSX_PAT` are securely stored as GitHub secrets
* Tokens have minimal required permissions (marketplace publish only)
* Extension files are built from source during workflow execution
* All steps logged for audit trail

## File Structure

```
.github/workflows/
└── vscode-extension-release.yml

tooling/github/vscode-extension/
└── github-release/
    └── action.yml
```

<Note>
  The workflow only triggers when the VSCode extension version specifically changes. GitHub releases use the tag format `vscode-v{version}` to distinguish from CLI releases.
</Note>

## Best Practices

* VSIX files are automatically attached to GitHub releases for manual distribution
* The automation follows the same patterns as the existing CLI release workflow for consistency
* Version management is handled by the NPM Release workflow with AI-powered changelog generation
* Dual marketplace publishing ensures maximum compatibility across VS Code distributions