Releasing Extensions

How to publish and distribute your Qwen Code extensions

Releasing Extensions

Once you’ve built an extension, you can share it with others. There are two primary methods for releasing extensions: through a Git repository or via GitHub Releases.

Distribution Methods

Git Repository (Recommended)

Pros:

• Simple to set up
• Flexible branching strategies
• Easy rollbacks
• Supports any Git hosting service

Cons:

• Requires full repository clone on install
• All files downloaded (including dev files)

Best for: Most extensions, especially those without build steps

GitHub Releases

Pros:

• Faster installation (single archive)
• Can include pre-built binaries
• Platform-specific builds
• Smaller download size

Cons:

• GitHub-specific
• Requires release workflow
• More complex setup

Best for: Extensions with build steps, platform-specific code, or large dependencies

Releasing Through Git Repository

This is the simplest and most flexible approach.

Setup

1. Create a Public Repository

   Create a public repository on GitHub, GitLab, or any Git hosting service:

   git init
   git add .
   git commit -m "Initial extension release"
   git remote add origin https://github.com/username/my-extension.git
   git push -u origin main
   

2. Users Install With

   # Full URL
   qwen extensions install https://github.com/username/my-extension
   
   # Shorthand (GitHub only)
   qwen extensions install username/my-extension
   

Version Management

Update the version in qwen-extension.json when you make changes:

{
  "name": "my-extension",
  "version": "1.1.0"
}

Commit and push:

git add qwen-extension.json
git commit -m "chore: bump version to 1.1.0"
git push

Users will be prompted to update when you push to the branch they’re tracking.

Managing Release Channels

Use branches or tags for different release channels:

Option 1: Branch-Based Channels

# Default branch (stable)
git checkout main

# Preview/beta channel
git checkout -b preview
git push origin preview

# Development channel
git checkout -b dev
git push origin dev

Users install:

# Stable (default branch)
qwen extensions install username/my-extension

# Preview
qwen extensions install username/my-extension --ref=preview

# Dev
qwen extensions install username/my-extension --ref=dev

Option 2: Tag-Based Versions

# Create release tags
git tag v1.0.0
git push origin v1.0.0

git tag v1.1.0
git push origin v1.1.0

Users install specific version:

qwen extensions install username/my-extension --ref=v1.0.0

Recommended Git Flow

For extensions with stable/preview/dev channels:

1. Development Branch (dev)

   • Active development happens here
   • Frequent changes
   • May be unstable

2. Preview Branch (preview)

   • Merge from dev when ready for testing
   • More stable than dev
   • Feature-complete for next release

3. Main Branch (main or master)

   • Production-ready
   • Only merge from preview after testing
   • Default installation target

Workflow:

# Develop
git checkout dev
# ... make changes ...
git commit -m "feat: add new feature"
git push

# Promote to preview
git checkout preview
git merge dev
git push

# After testing, promote to stable
git checkout main
git merge preview
git push

Auto-Update

Users can enable auto-updates:

qwen extensions install username/my-extension --auto-update

Their installation will automatically update when you push changes to the tracked branch.

Releasing Through GitHub Releases

GitHub Releases provide a more optimized installation experience.

Creating a Release

1. Tag Your Version

   git tag v1.0.0
   git push origin v1.0.0
   

2. Create Release on GitHub

   Go to your repository on GitHub:

   • Click “Releases” → “Create a new release”
   • Select your tag (v1.0.0)
   • Add title and description
   • Attach assets (if needed)
   • Check “Set as the latest release”
   • Click “Publish release”

3. Users Install

   qwen extensions install username/my-extension
   

   Qwen Code automatically detects and uses GitHub Releases.

Simple Releases (No Build)

If your extension doesn’t require a build step:

1. Tag and push
2. Create GitHub release
3. GitHub automatically creates archive

Done! No manual asset creation needed.

Custom Pre-Built Archives

For extensions with build steps or platform-specific code:

Archive Structure

Archives must contain the complete extension at the root:

my-extension.tar.gz
└── (root)
    ├── qwen-extension.json
    ├── dist/
    │   └── server.js
    └── README.md

Not like this:

❌ my-extension.tar.gz
    └── my-extension/          # Extra nesting level
        ├── qwen-extension.json
        └── ...

Platform-Specific Assets

Naming convention for platform-specific archives:

Format: {platform}.{arch}.{name}.{extension}

Platform values:

• darwin - macOS
• linux - Linux
• win32 - Windows

Architecture values:

• x64 - x86-64/AMD64
• arm64 - ARM 64-bit

Extensions:

• .tar.gz - Recommended for macOS/Linux
• .zip - Recommended for Windows

Examples:

darwin.arm64.my-extension.tar.gz    # Apple Silicon Macs
darwin.x64.my-extension.tar.gz      # Intel Macs
linux.x64.my-extension.tar.gz       # Linux x86-64
linux.arm64.my-extension.tar.gz     # Linux ARM64
win32.x64.my-extension.zip          # Windows x86-64

Platform-only (any architecture):

darwin.my-extension.tar.gz          # All Macs
linux.my-extension.tar.gz           # All Linux
win32.my-extension.zip              # All Windows

Generic (single asset):

If you attach only one asset, it’s used for all platforms:

my-extension.tar.gz                 # Works everywhere

Building Platform Archives

Example build script:

scripts/build-release.sh:

#!/bin/bash
set -e

VERSION=$1
NAME="my-extension"

if [ -z "$VERSION" ]; then
  echo "Usage: $0 <version>"
  exit 1
fi

# Clean
rm -rf dist release
mkdir -p release

# Build
npm run build

# Create base archive structure
mkdir -p build-temp
cp qwen-extension.json build-temp/
cp -r dist build-temp/
cp README.md build-temp/

# Platform-specific builds
cd build-temp

# macOS ARM64
tar -czf ../release/darwin.arm64.${NAME}.tar.gz .

# macOS x64
tar -czf ../release/darwin.x64.${NAME}.tar.gz .

# Linux x64
tar -czf ../release/linux.x64.${NAME}.tar.gz .

# Windows x64
zip -r ../release/win32.x64.${NAME}.zip .

cd ..
rm -rf build-temp

echo "Archives created in release/"
ls -lh release/

Usage:

chmod +x scripts/build-release.sh
./scripts/build-release.sh v1.0.0

GitHub Actions Workflow

Automate releases with GitHub Actions:

.github/workflows/release.yml:

name: Release Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Create archives
        run: |
          mkdir -p release
          
          # Create base structure
          mkdir -p build-temp
          cp qwen-extension.json build-temp/
          cp -r dist build-temp/
          cp README.md build-temp/
          
          # Create platform archives
          cd build-temp
          tar -czf ../release/darwin.arm64.my-extension.tar.gz .
          tar -czf ../release/darwin.x64.my-extension.tar.gz .
          tar -czf ../release/linux.x64.my-extension.tar.gz .
          zip -r ../release/win32.x64.my-extension.zip .
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: release/*
          draft: false
          prerelease: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Trigger a release:

git tag v1.0.0
git push origin v1.0.0

GitHub Actions automatically builds and creates the release.

Pre-Release Versions

Create pre-releases for testing:

git tag v1.1.0-beta.1
git push origin v1.1.0-beta.1

On GitHub, check “Set as a pre-release” when creating the release.

Users opt-in to pre-releases:

qwen extensions install username/my-extension --pre-release

Extension README

Include a comprehensive README in your extension:

README.md:

# My Extension Name

Brief description of what your extension does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

\`\`\`bash
qwen extensions install username/my-extension
\`\`\`

## Configuration

This extension requires:

1. API key from [Service Name](https://example.com)
2. Configure with:
   \`\`\`bash
   qwen extensions settings set my-extension "API Key"
   \`\`\`

## Usage

### Commands

- `/command-name` - Description
- `/other-command` - Description

### Tools

- `tool_name` - What it does
- `other_tool` - What it does

## Examples

\`\`\`
Example usage here
\`\`\`

## Development

To work on this extension:

\`\`\`bash
git clone https://github.com/username/my-extension
cd my-extension
npm install
npm run build
qwen extensions link .
\`\`\`

## License

MIT

Best Practices

1. Semantic Versioning

Use Semantic Versioning:

• 1.0.0 - Initial release
• 1.0.1 - Bug fix
• 1.1.0 - New feature (backwards compatible)
• 2.0.0 - Breaking change

2. Changelog

Maintain a CHANGELOG.md:

# Changelog

## [1.1.0] - 2024-01-15

### Added
- New `search` command
- Support for filtering results

### Fixed
- Issue with API timeout

### Changed
- Improved error messages

## [1.0.0] - 2024-01-01

- Initial release

3. Git Tags

Tag all releases:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

4. Clean Repository

Exclude unnecessary files:

.gitignore:

node_modules/
dist/
*.log
.DS_Store
.env

For GitHub Releases, include built files in archives but not in the repository.

5. License

Include a LICENSE file:

MIT License

Copyright (c) 2024 Your Name

Permission is hereby granted...

6. Documentation

Provide clear documentation:

• README with installation and usage
• Examples for all features
• Configuration instructions
• Troubleshooting section

Testing Before Release

Local Testing

# Link for testing
qwen extensions link .

# Test all features
# ...

# Unlink when done
qwen extensions uninstall my-extension

Install from Git (Before Release)

Push to a branch and test installation:

git checkout -b test-release
git push origin test-release

qwen extensions install username/my-extension --ref=test-release

Verify everything works, then merge to main and create release.

Updating Extensions

When users have your extension installed:

Git Repository Installs

Users update with:

qwen extensions update my-extension

Or update all:

qwen extensions update --all

GitHub Release Installs

Users are notified when new releases are available. They can update with:

qwen extensions update my-extension

Troubleshooting

”Extension not found”

Ensure:

• Repository is public
• qwen-extension.json is in root
• Repository URL is correct

”Invalid extension structure”

Verify:

• Archive has extension files at root (no extra nesting)
• qwen-extension.json is valid JSON
• Required files are included

”Build files missing”

For extensions with build steps:

• Include built files in archives
• Don’t rely on users building
• Test archive contents before release

Next Steps

• Best Practices - Extension development guidelines
• Creating Extensions - Build an extension
• MCP Servers - Add custom tools