qwen-code/docs/users/extension/extension-releasing.md

Extension Releasing

There are three primary ways of releasing extensions to users:

• Git repository
• Github Releases
• npm Registry

Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files. npm registry releases are ideal for teams that already use npm for package distribution, especially with private registries.

Releasing through a git repository

This is the most flexible and simple option. All you need to do us create a publicly accessible git repo (such as a public github repository) and then users can install your extension using qwen extensions install <your-repo-uri>, or for a GitHub repository they can use the simplified qwen extensions install <org>/<repo> format. They can optionally depend on a specific ref (branch/tag/commit) using the --ref=<some-ref> argument, this defaults to the default branch.

Whenever commits are pushed to the ref that a user depends on, they will be prompted to update the extension. Note that this also allows for easy rollbacks, the HEAD commit is always treated as the latest version regardless of the actual version in the qwen-extension.json file.

Managing release channels using a git repository

Users can depend on any ref from your git repo, such as a branch or tag, which allows you to manage multiple release channels.

For instance, you can maintain a stable branch, which users can install this way qwen extensions install <your-repo-uri> --ref=stable. Or, you could make this the default by treating your default branch as your stable release branch, and doing development in a different branch (for instance called dev). You can maintain as many branches or tags as you like, providing maximum flexibility for you and your users.

Note that these ref arguments can be tags, branches, or even specific commits, which allows users to depend on a specific version of your extension. It is up to you how you want to manage your tags and branches.

Example releasing flow using a git repo

While there are many options for how you want to manage releases using a git flow, we recommend treating your default branch as your "stable" release branch. This means that the default behavior for qwen extensions install <your-repo-uri> is to be on the stable release branch.

Lets say you want to maintain three standard release channels, stable, preview, and dev. You would do all your standard development in the dev branch. When you are ready to do a preview release, you merge that branch into your preview branch. When you are ready to promote your preview branch to stable, you merge preview into your stable branch (which might be your default branch or a different branch).

You can also cherry pick changes from one branch into another using git cherry-pick, but do note that this will result in your branches having a slightly divergent history from each other, unless you force push changes to your branches on each release to restore the history to a clean slate (which may not be possible for the default branch depending on your repository settings). If you plan on doing cherry picks, you may want to avoid having your default branch be the stable branch to avoid force-pushing to the default branch which should generally be avoided.

Releasing through Github releases

Qwen Code extensions can be distributed through GitHub Releases. This provides a faster and more reliable initial installation experience for users, as it avoids the need to clone the repository.

Each release includes at least one archive file, which contains the full contents of the repo at the tag that it was linked to. Releases may also include pre-built archives if your extension requires some build step or has platform specific binaries attached to it.

When checking for updates, qwen code will just look for the latest release on github (you must mark it as such when creating the release), unless the user installed a specific release by passing --ref=<some-release-tag>. We do not at this time support opting in to pre-release releases or semver.

Custom pre-built archives

Custom archives must be attached directly to the github release as assets and must be fully self-contained. This means they should include the entire extension, see archive structure.

If your extension is platform-independent, you can provide a single generic asset. In this case, there should be only one asset attached to the release.

Custom archives may also be used if you want to develop your extension within a larger repository, you can build an archive which has a different layout from the repo itself (for instance it might just be an archive of a subdirectory containing the extension).

Platform specific archives

To ensure Qwen Code can automatically find the correct release asset for each platform, you must follow this naming convention. The CLI will search for assets in the following order:

1. Platform and Architecture-Specific: {platform}.{arch}.{name}.{extension}
2. Platform-Specific: {platform}.{name}.{extension}
3. Generic: If only one asset is provided, it will be used as a generic fallback.

• {name}: The name of your extension.
• {platform}: The operating system. Supported values are:
  • darwin (macOS)
  • linux
  • win32 (Windows)
• {arch}: The architecture. Supported values are:
  • x64
  • arm64
• {extension}: The file extension of the archive (e.g., .tar.gz or .zip).

Examples:

• darwin.arm64.my-tool.tar.gz (specific to Apple Silicon Macs)
• darwin.my-tool.tar.gz (for all Macs)
• linux.x64.my-tool.tar.gz
• win32.my-tool.zip

Archive structure

Archives must be fully contained extensions and have all the standard requirements - specifically the qwen-extension.json file must be at the root of the archive.

The rest of the layout should look exactly the same as a typical extension, see extensions.md.

Example GitHub Actions workflow

Here is an example of a GitHub Actions workflow that builds and releases a Qwen Code extension for multiple platforms:

name: Release Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'

      - name: Install dependencies
        run: npm ci

      - name: Build extension
        run: npm run build

      - name: Create release assets
        run: |
          npm run package -- --platform=darwin --arch=arm64
          npm run package -- --platform=linux --arch=x64
          npm run package -- --platform=win32 --arch=x64

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/darwin.arm64.my-tool.tar.gz
            release/linux.arm64.my-tool.tar.gz
            release/win32.arm64.my-tool.zip

Releasing through npm registry

You can publish Qwen Code extensions as scoped npm packages (e.g. @your-org/my-extension). This is a good fit when:

• Your team already uses npm for package distribution
• You need private registry support with existing auth infrastructure
• You want version resolution and access control handled by npm

Package requirements

Your npm package must include a qwen-extension.json file at the package root. This is the same config file used by all Qwen Code extensions — the npm tarball is simply another delivery mechanism.

A minimal package structure looks like:

my-extension/
├── package.json
├── qwen-extension.json
├── QWEN.md              # optional context file
├── commands/             # optional custom commands
├── skills/               # optional custom skills
└── agents/               # optional custom subagents

Make sure qwen-extension.json is included in your published package (i.e. not excluded by .npmignore or the files field in package.json).

Publishing

Use standard npm publishing tools:

# Publish to the default registry
npm publish

# Publish to a private/custom registry
npm publish --registry https://your-registry.com

Installation

Users install your extension using the scoped package name:

# Install latest version
qwen extensions install @your-org/my-extension

# Install a specific version
qwen extensions install @your-org/[email protected]

# Install from a custom registry
qwen extensions install @your-org/my-extension --registry https://your-registry.com

Update behavior

• Extensions installed without a version pin (e.g. @scope/pkg) track the latest dist-tag.
• Extensions installed with a dist-tag (e.g. @scope/pkg@beta) track that specific tag.
• Extensions pinned to an exact version (e.g. @scope/[email protected]) are always considered up-to-date and will not prompt for updates.

Authentication for private registries

Qwen Code reads npm auth credentials automatically:

1. NPM_TOKEN environment variable — highest priority
2. .npmrc file — supports both host-level and path-scoped _authToken entries (e.g. //your-registry.com/:_authToken=TOKEN or //pkgs.dev.azure.com/org/_packaging/feed/npm/registry/:_authToken=TOKEN)

.npmrc files are read from the current directory and the user's home directory.

Managing release channels

You can use npm dist-tags to manage release channels:

# Publish a beta release
npm publish --tag beta

# Users install beta channel
qwen extensions install @your-org/my-extension@beta

This works similarly to git branch-based release channels but uses npm's native dist-tag mechanism.