Skip to content

RELEASE_SETUP.md

Latest commit

 

History

History
187 lines (139 loc) · 8.03 KB

RELEASE_SETUP.md

File metadata and controls

187 lines (139 loc) · 8.03 KB
Raw

Release Pipeline Setup Guide

This document explains how to configure the GitHub infrastructure for the Windows MCP Server release pipeline.

Overview

The release workflow (.github/workflows/release-unified.yml) is a unified workflow that builds and publishes all Windows MCP Server components (standalone binaries and VS Code extension) with a single version number.

LLM integration tests are intentionally manual-only. They are never invoked by PR, CI, or release workflows; run them separately through the dedicated LLM Integration Tests workflow when needed.

The release workflow requires the GitHub Secrets configuration for VS Code Marketplace publishing described below.

Architecture

┌─────────────────────┐   Manual Trigger    ┌─────────────────────┐
│   GitHub Actions    │ ──(workflow_dispatch)│  Release Workflow   │
│   (windows-latest)  │                      │  (unified)          │
└─────────────────────┘                      └─────────────────────┘
         │                                            │
         │ Version Calculation                        │
         ▼                                            ▼
┌─────────────────────┐                      ┌─────────────────────┐
│  Build Standalone   │                      │  Build VS Code Ext  │
│  (x64, ARM64)       │                      │  (VSIX + Publish)   │
└─────────────────────┘                      └─────────────────────┘
         │                                            │
         │                                            │
         └────────────────┬───────────────────────────┘
                          │
                          ▼
                 ┌─────────────────────┐
                 │  Create Git Tag     │
                 │  (v1.2.3)           │
                 └─────────────────────┘
                          │
                          ▼
                 ┌─────────────────────┐
                 │  GitHub Release     │
                 │  (with artifacts)   │
                 └─────────────────────┘

Step 1: Configure GitHub Secrets

Go to your GitHub repository → Settings → Secrets and variables → Actions.

Required Secrets

Secret Name Value Description
VSCE_TOKEN xxxxxxxx... VS Code Marketplace Personal Access Token (required for publishing)

Getting a VSCE Token

  1. Go to Azure DevOps
  2. Click your profile → Personal Access Tokens
  3. Create new token:
    • Name: vsce-mcp-windows
    • Organization: All accessible organizations
    • Scopes: Marketplace → Manage
  4. Copy the token (shown only once!)

Manual LLM Tests

LLM tests run against GPT-5.5 via GitHub Copilot. They are intentionally isolated from releases and all automatic workflows. To run them, open GitHub Actions, select LLM Integration Tests, choose Run workflow, and optionally specify one scenario. The model is configured in tests/Sbroenne.WindowsMcp.LLM.Tests/conftest.py.

How to Release

The new release process uses a unified workflow that is triggered manually via workflow_dispatch:

  1. Go to GitHub Actions → "Release All Components"
  2. Click "Run workflow"
  3. Select version bump type:
    • patch: 1.2.3 → 1.2.4 (bug fixes)
    • minor: 1.2.3 → 1.3.0 (new features)
    • major: 1.2.3 → 2.0.0 (breaking changes)
  4. Or enter a custom version (e.g., "1.5.0")
  5. Click "Run workflow"

The workflow will:

  1. Calculate the next version from the latest v* tag
  2. Build standalone binaries (win-x64, win-arm64)
  3. Build VS Code extension (VSIX)
  4. Create and push the git tag (e.g., v1.2.4)
  5. Publish to VS Code Marketplace
  6. Create GitHub release with all artifacts

Test a Release (Dry Run)

To test the workflow without publishing:

  1. Go to GitHub Actions → "Release All Components"
  2. Run with a custom version like "0.0.0-test"
  3. The workflow will build everything but create a test tag
  4. You can then manually delete the test tag and release: 
    git tag -d v0.0.0-test
git push origin :refs/tags/v0.0.0-test
gh release delete v0.0.0-test --yes

Verification

After setup, verify the configuration:

Test LLM Connection (Optional)

Only needed if you want to run LLM tests locally:

# Authenticate with GitHub (Copilot access required)
gh auth login
# or set a token directly:
$env:GITHUB_TOKEN = "<your-copilot-enabled-token>"

# Run a quick test
cd tests/Sbroenne.WindowsMcp.LLM.Tests
uv run pytest -v

Troubleshooting

LLM tests fail to authenticate

For local runs, confirm gh auth status succeeds or that GITHUB_TOKEN is set to a Copilot-enabled token. For GitHub-hosted runs, use the dedicated manual LLM Integration Tests workflow.

LLM Tests Fail with "No GUI session"

GitHub Actions windows-latest runners have a desktop session by default. If tests fail with GUI errors:

  • Ensure tests don't require interactive user input
  • Check that target applications (Notepad, Paint, etc.) are available on the runner

Security Considerations

  1. No secrets in code — All credentials are in GitHub Secrets
  2. Manual approval — Releases are triggered manually via workflow_dispatch, not automatically on push
  3. Test isolation — LLM tests can only be started through their dedicated workflow_dispatch trigger

Migration from Old Release Process

If you were using the old tag-based release workflows (release.yml, release-mcp-server.yml, release-vscode-extension.yml), you need to:

  1. Clean up old tags: The old process created separate tags for MCP server (mcp-v*) and VS Code extension (vscode-v*). The new unified process uses only v* tags.

    Run the cleanup script to remove old tags:

    # Dry run first to see what will be deleted
.\.github\scripts\cleanup-old-tags.ps1 -DryRun

# Actually delete the tags
.\.github\scripts\cleanup-old-tags.ps1

    This will delete:

    • All mcp-v* tags (e.g., mcp-v1.1.0, mcp-v1.2.0)
    • All vscode-v* tags (e.g., vscode-v1.1.0, vscode-v1.2.0)
    • Keep all v* tags (e.g., v1.3.6)

  2. Remove old workflows: Delete the old workflow files:

    git rm .github/workflows/release.yml
git rm .github/workflows/release-mcp-server.yml
git rm .github/workflows/release-vscode-extension.yml

  3. Use the new workflow: Going forward, use "Release All Components" workflow from the Actions tab. It will automatically calculate the next version from the latest v* tag.

Why the Change?

The old process had several issues:

  • Version inconsistency: Separate tags (v*, mcp-v*, vscode-v*) could get out of sync
  • Complex: Three separate workflows with duplicated logic
  • Error-prone: Manual tag creation required, easy to make mistakes
  • Inefficient: Required multiple releases to publish both components

The new unified workflow:

  • ✅ Single version for all components
  • ✅ Automatic versioning with semantic version bumps
  • ✅ Single workflow for all release steps
  • ✅ Manual trigger with clear version bump options
  • ✅ Consistent with mcp-server-excel for easier maintenance

References