claude-task-master/apps/extension/docs/extension-CI-setup.md

VS Code Extension CI/CD Setup

This document explains the CI/CD setup for the Task Master VS Code extension.

🔄 Workflows Overview

1. Extension CI (extension-ci.yml)

Triggers:

• Push to main or next branches (only when extension files change)
• Pull requests to main or next (only when extension files change)

What it does:

• ✅ Lints and type-checks the extension code
• 🔨 Builds the extension (pnpm run build)
• 📦 Creates a clean package (pnpm run package)
• 🧪 Runs tests with VS Code test framework
• 📋 Creates a test VSIX package to verify packaging works
• 💾 Uploads build artifacts for inspection

2. Extension Release (extension-release.yml)

Triggers:

• Push to main branch (only when extension files change AND version changes)
• Manual trigger with workflow_dispatch (with optional force publish)

What it does:

• 🔍 Checks if the extension version changed
• 🧪 Runs full test suite (lint, typecheck, tests)
• 🔨 Builds and packages the extension
• 📤 Publishes to VS Code Marketplace
• 🌍 Publishes to Open VSX Registry (for VSCodium, Gitpod, etc.)
• 🏷️ Creates a GitHub release with the VSIX file
• 📊 Uploads release artifacts

🔑 Required Secrets

To use the release workflow, you need to set up these GitHub repository secrets:

VSCE_PAT (VS Code Marketplace Personal Access Token)

1. Go to Azure DevOps
2. Sign in with your Microsoft account
3. Create a Personal Access Token:
   • Name: VS Code Extension Publishing
   • Organization: All accessible organizations
   • Expiration: Custom (recommend 1 year)
   • Scopes: Custom defined → Marketplace → Manage
4. Copy the token and add it to GitHub Secrets as VSCE_PAT

OVSX_PAT (Open VSX Registry Personal Access Token)

1. Go to Open VSX Registry
2. Sign in with your GitHub account
3. Go to your User Settings
4. Create a new Access Token:
   • Description: VS Code Extension Publishing
   • Scopes: Leave default (full access)
5. Copy the token and add it to GitHub Secrets as OVSX_PAT

GITHUB_TOKEN (automatically provided)

This is automatically available in GitHub Actions - no setup required.

🚀 Publishing Process

Automatic Publishing (Recommended)

1. Make changes to the extension code
2. Update version in both:
   • apps/extension/package.json
   • apps/extension/package.publish.json
3. Commit and push to main branch
4. CI automatically triggers and publishes if version changed

Manual Publishing

1. Go to Actions tab in GitHub
2. Select Extension Release workflow
3. Click Run workflow
4. Check "Force publish even without version changes" if needed
5. Click Run workflow

📋 Version Management

Version Sync Checklist

When updating the extension version, ensure these fields match in both files:

package.json and package.publish.json:

{
  "version": "1.0.2",                    // ⚠️ MUST MATCH
  "publisher": "DavidMaliglowka",        // ⚠️ MUST MATCH  
  "displayName": "Task Master Kanban",   // ⚠️ MUST MATCH
  "description": "...",                  // ⚠️ MUST MATCH
  "engines": { "vscode": "^1.93.0" },   // ⚠️ MUST MATCH
  "categories": [...],                   // ⚠️ MUST MATCH
  "contributes": { ... }                 // ⚠️ MUST MATCH
}

Version Detection Logic

The release workflow only publishes when:

• Extension files changed in the push, AND
• Version field changed in package.json or package.publish.json

🔍 Monitoring Builds

CI Status

• Green ✅: Extension builds and tests successfully
• Red ❌: Build/test failures - check logs for details
• Yellow 🟡: Partial success - some jobs may have warnings

Release Status

• Published 🎉: Extension live on VS Code Marketplace
• Skipped ℹ️: No version changes detected
• Failed ❌: Check logs - often missing secrets or build issues

Artifacts

Both workflows upload artifacts that you can download:

• CI: Test results, built files, and VSIX package
• Release: Final VSIX package and build artifacts (90-day retention)

🛠️ Troubleshooting

Common Issues

"VSCE_PAT is not set" Error

• Ensure VSCE_PAT secret is added to repository
• Check token hasn't expired
• Verify token has Marketplace > Manage permissions

"OVSX_PAT is not set" Error

• Ensure OVSX_PAT secret is added to repository
• Check token hasn't expired
• Verify you're signed in to Open VSX Registry with GitHub

"Version not changed" Skipped Release

• Update version in both package.json AND package.publish.json
• Ensure files are committed and pushed
• Use manual trigger with force publish if needed

Build Failures

• Check extension code compiles locally: cd apps/extension && pnpm run build
• Verify tests pass locally: pnpm run test
• Check for TypeScript errors: pnpm run check-types

Packaging Failures

• Ensure clean package builds: pnpm run package
• Check vsix-build structure is correct
• Verify package.publish.json has correct fields

📁 File Structure Impact

The CI workflows respect the 3-file packaging system:

• Development: Uses package.json for dependencies and scripts
• Release: Uses package.publish.json for clean marketplace package
• Build: Uses package.mjs to create vsix-build/ for final packaging

This ensures clean, conflict-free publishing to both VS Code Marketplace and Open VSX Registry! 🚀

🌍 Dual Registry Publishing

Your extension will be automatically published to both:

• VS Code Marketplace - For official VS Code users
• Open VSX Registry - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors