How Plugin Versions Interact with the Marketplace Update Mechanism in OpenAI Plugins

Plugin versions defined in .codex-plugin/plugin.json serve as the single source of truth that marketplaces use to detect new releases, trigger update notifications, validate API compatibility, and maintain auditable deployment records.

In the OpenAI Plugins repository, every plugin's version is declared in a machine-readable manifest file that governs the entire marketplace update lifecycle. Understanding how these version strings interact with marketplace backends is critical for developers publishing to platforms like Zoom Marketplace or Google Workspace Marketplace, as mismatches or forgotten version bumps can silently fail deployments or block user updates.

Where Plugin Versions Are Defined

Each plugin stores its canonical version in a .codex-plugin/plugin.json manifest file. For example, in plugins/zoom/.codex-plugin/plugin.json, the version field appears as "version": "1.0.2" according to the repository source code. This JSON field is the authoritative value that marketplace portals read during the upload process.

Similar manifests exist across the repository, such as plugins/zotero/.codex-plugin/plugin.json (version 0.1.2) and plugins/zoho/.codex-plugin/plugin.json (version 1.0.3), demonstrating how each plugin maintains independent versioning.

How Marketplaces Process Version Metadata

When a developer publishes a plugin, the marketplace extracts the version string from the manifest and performs four critical functions:

Detecting New Releases

The marketplace compares the incoming version against the currently listed version using semantic-version comparison. If the new version is higher, the marketplace replaces the older bundle; otherwise, the upload is rejected as a duplicate.

Driving Update Notifications

A higher version triggers end-user update prompts. When the marketplace registers a version change, it automatically surfaces "Update available" notifications in client applications like Zoom or Chrome extensions.

Validating API Compatibility

Some marketplaces enforce version ranges for dependent APIs. If a plugin's version declares new capabilities that exceed the client SDK version, the marketplace surfaces PERMISSION_DENIED or unsupportedApis errors in the UI, preventing incompatible deployments.

Recording Auditable Metadata

The version is persisted in runtime manifests such as run_manifest.json, which captures the exact plugin version alongside argv and environment snapshots. This ensures reproducibility for debugging and compliance audits.

The Marketplace Update Workflow

The interaction between plugin versions and marketplace updates follows a strict sequence:

1. Version Bump: The developer edits .codex-plugin/plugin.json and increments the "version" field.
2. Package Build: The build process (e.g., npm pack or Python setup.py) bakes the version into the archive metadata.
3. Upload: The developer submits the bundle to the marketplace portal (e.g., Zoom Marketplace → Your App → Version tab).
4. Validation: The marketplace backend validates the version against existing listings, API compatibility matrices, and domain allow-lists.
5. Activation: If valid, the new bundle replaces the old one, and users receive update prompts on their next client sync.

Because the version is the sole determinant of "newness," any functional change—whether feature additions, dependency updates, or security header modifications—must be accompanied by a version increment. Failure to bump the version results in either silent redeployment of identical binaries or rejection by the marketplace's "new version required" checks.

Working with Plugin Versions Programmatically

Reading a Plugin Version (Python)

To extract the version programmatically from the manifest:

import json
import pathlib

def get_plugin_version(plugin_dir: pathlib.Path) -> str:
    """Return the version string from a .codex-plugin/plugin.json file."""
    manifest_path = plugin_dir / ".codex-plugin" / "plugin.json"
    with manifest_path.open() as f:
        data = json.load(f)
    return data["version"]

# Example usage for the Zoom plugin:

zoom_dir = pathlib.Path("plugins/zoom")
print("Zoom plugin version →", get_plugin_version(zoom_dir))

When executed within the repository, this outputs:

Zoom plugin version → 1.0.2

Automating Version Bumps (Bash/Node.js)

For automated CI/CD pipelines, bump the patch version using jq:

jq '.version |= (. + 0.0.1 | tostring)' \
   plugins/zoom/.codex-plugin/plugin.json > tmp.json && \
mv tmp.json plugins/zoom/.codex-plugin/plugin.json

After bumping, run your packaging script (e.g., npm pack) before uploading to the marketplace.

Uploading to Zoom Marketplace

When submitting via CLI tools, the version is extracted from the manifest:

zoom-cli upload \
  --app-id $ZOOM_APP_CLIENT_ID \
  --secret $ZOOM_APP_CLIENT_SECRET \
  --manifest plugins/zoom/.codex-plugin/plugin.json \
  --bundle dist/zoom-plugin.zip

The CLI transmits the version to Zoom's API, which validates that it is newer than the existing listing before accepting the update.

Summary

• Source of truth: Plugin versions live in .codex-plugin/plugin.json files (e.g., plugins/zoom/.codex-plugin/plugin.json).
• Update detection: Marketplaces use semantic version comparison to identify new releases and reject duplicates.
• Compatibility gates: Version declarations trigger validation against client SDK capabilities, surfacing PERMISSION_DENIED or unsupportedApis errors for mismatches.
• Audit trails: Runtime manifests like run_manifest.json record the exact version for reproducibility.
• Deployment requirement: Every functional change must increment the version to trigger marketplace updates and user notifications.

Frequently Asked Questions

What happens if I upload a plugin without bumping the version?

The marketplace will either reject the upload as a duplicate or silently redeploy the same binary without triggering user update notifications. Because the version string is the primary key for "newness," unchanged versions signal that no update is required, leaving users on stale builds.

Where exactly does the marketplace read the plugin version from?

The marketplace reads the top-level "version" field from the .codex-plugin/plugin.json file within your plugin directory. In the OpenAI Plugins repository, this file is located at paths like plugins/zoom/.codex-plugin/plugin.json for each respective integration.

How do plugin versions affect API compatibility validation?

Marketplaces compare the plugin version against supported client SDK version ranges. If your version declares capabilities that require a newer client than what the user has installed, the marketplace blocks installation and returns errors such as PERMISSION_DENIED or unsupportedApis to prevent runtime crashes.

Can I use semantic versioning (SemVer) for plugin versions?

Yes, the OpenAI Plugins repository uses semantic versioning (e.g., 1.0.2, 0.1.2), and marketplaces perform semantic-version comparisons to determine if an upload represents an upgrade. You should follow SemVer standards (MAJOR.MINOR.PATCH) to ensure predictable update behavior across marketplace platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}