Plugin Versioning Strategies and Update Mechanisms for OpenAI Plugins

OpenAI plugins implement a multi-layered versioning architecture that combines semantic manifest versioning, SDK dependency pinning, and workflow-level versioning to guarantee safe updates and backward compatibility across the Codex-plugin ecosystem.

OpenAI plugins are distributed as Codex-plugin bundles that contain a mandatory manifest file and optional skill implementations. Understanding the plugin versioning strategies and update mechanisms for OpenAI plugins is critical for developers who need to maintain compatibility while evolving their functionality. The openai/plugins repository defines five complementary versioning layers that interact during development, validation, and runtime to prevent breaking changes.

The Five Layers of Plugin Versioning

The repository structures versioning into five distinct layers, each controlling a different aspect of the plugin lifecycle.

Plugin Manifest Version

The plugin manifest version controls the overall bundle definition, including the plugin name, description, required scopes, and skill inventory. This version uses semantic versioning (MAJOR.MINOR.PATCH) and is declared in the mandatory .codex-plugin/plugin.json file. According to the repository root README, every plugin must reside under plugins/<name>/ and include this manifest file.

API (SDK) Version

The API (SDK) version specifies the underlying SDK that the plugin code expects, such as Zoom's @zoom/appssdk pinned to ^0.16.26. This layer prevents runtime failures by ensuring the host environment provides compatible APIs. The Zoom SDK migration documentation in plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md demonstrates how the version field in the config() method enforces these constraints.

Skill and Language Versioning

Individual skill implementations may evolve independently using language-specific strategies. For Temporal-based workflows, developers use worker versioning to handle logic changes without breaking in-flight executions. The Temporal core versioning guide in plugins/temporal/skills/temporal-developer/references/core/versioning.md outlines three approaches: pinning, patching via GetVersion, and worker versioning.

Data and Asset Versioning

Data resources use incremental versioning to ensure consistency during updates. For example, Wix catalog items use integer or UUID-based versioning stored alongside asset metadata. The Wix catalog documentation in plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md explains how previous versions must be retained to support rollback operations.

Marketplace Manifest Validation

The marketplace validation layer ensures submitted manifests match the current schema before acceptance. The validation endpoint POST /marketplace/apps/manifest/validate checks for schema mismatches and stale API references. This mechanism is documented in the Zoom REST API reference at plugins/zoom/skills/rest-api/references/marketplace-apps.md.

How the Versioning Layers Interact

These five layers operate sequentially across the plugin lifecycle to ensure safe distribution and execution.

1. Development – Developers create a new bundle by updating .codex-plugin/plugin.json with a new manifest_version and ensuring the api_version matches the SDKs used in skill code.

2. CI Validation – Before publishing, continuous integration runs the manifest validator against the POST /marketplace/apps/manifest/validate endpoint. This catches missing required fields or incompatible SDK references.

3. Marketplace Ingestion – The marketplace stores each manifest as a versioned artifact, creating immutable versions while retaining previous releases. This enables rollbacks and side-by-side testing.

4. Runtime Drift Handling – Clients query the manifest at startup. If the client's SDK version is older than the manifest's api_version, the SDK reports a drift warning and falls back to legacy keys where required, as documented in plugins/zoom/skills/virtual-agent/references/versioning-and-drift.md.

5. Update Propagation – When a new version publishes, the marketplace notifies installed instances via webhook or polling. Clients download updated manifests respecting compatibility constraints defined in fields like unsupportedApis.

Key Update Mechanisms

The repository implements specific mechanisms to enforce these versioning strategies during updates.

Manifest Validation Endpoint

The marketplace provides a validation endpoint that verifies manifests comply with the current schema before acceptance. This prevents drift between the production definition and submitted plugins.

Automated CI Pipelines

Build workflows such as npx wix build && npx wix generate manifest or npm run lint && npm run test catch version mismatches early in the development cycle, as implemented in the Wix build workflow.

Worker Versioning for Temporal

When workflow definitions change, developers increment versions in the workflow code. The Temporal server uses GetVersion to route in-flight executions to the appropriate handler, ensuring non-breaking updates.

SDK Version Pinning

Zoom apps embed SDK versions in the config() call, causing the client to refuse execution if the installed SDK does not satisfy the required version. This is visible throughout the Zoom SDK examples where version: '0.16' appears frequently.

Catalog Versioning for Wix

The Wix API exposes GET /catalog/version endpoints, allowing plugins to fetch the latest catalog snapshot before modifying data, preventing conflicts during concurrent updates.

Code Examples

Bumping the Plugin Manifest Version

Update the semantic version in .codex-plugin/plugin.json to signal a new release:

{
  "name": "my-awesome-plugin",
  "description": "A demo plugin for OpenAI",
  "manifest_version": "1.2.0",
  "api_version": "2.0.0",
  "skills": [
    "skills/example-skill"
  ]
}

Source: Repository root README defining the required manifest schema.

Pinning an SDK Version in Zoom

Explicitly declare SDK compatibility in the application configuration:

import { ZoomApp } from '@zoom/appssdk';

ZoomApp.config({
  version: '0.16',
  clientId: process.env.ZOOM_CLIENT_ID,
  // additional configuration
});

Source: Zoom SDK examples in plugins/zoom/skills/zoom-apps-sdk/examples/quick-start.md.

Temporal Workflow Versioning

Use Workflow.getVersion to handle logic changes without breaking existing executions:

import { proxyActivities, proxySignal, Workflow } from '@temporalio/workflow';

export const VERSION = {
  MY_WORKFLOW: 2,
};

export const myWorkflow = Workflow.define('my-workflow', async () => {
  const version = Workflow.getVersion('my-workflow', 1, VERSION.MY_WORKFLOW);
  if (version === 1) {
    // legacy logic
  } else {
    // current logic
  }
});

Source: Temporal versioning documentation in plugins/temporal/skills/temporal-developer/references/core/versioning.md.

Checking Wix Catalog Version Before Updates

Verify catalog consistency before modifying product data:

import fetch from 'node-fetch';

async function updateProduct(productId, data) {
  const catalogRes = await fetch('https://www.wixapis.com/stores/v1/catalog/version');
  const { version } = await catalogRes.json();

  await fetch(`https://www.wixapis.com/stores/v1/products/${productId}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'Wix-Catalog-Version': version,
    },
    body: JSON.stringify(data),
  });
}

Source: Wix catalog versioning guide in plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md.

Summary

OpenAI plugins employ a comprehensive versioning strategy that spans multiple layers of the architecture:

• Semantic manifest versioning in .codex-plugin/plugin.json controls the overall bundle release cycle.
• SDK pinning prevents runtime failures by enforcing minimum API versions in host environments.
• Worker versioning allows Temporal workflows to evolve without breaking in-flight executions.
• Data versioning ensures consistency across catalog updates and asset modifications.
• Marketplace validation guarantees schema compliance before distribution through automated endpoints.

Frequently Asked Questions

How does the OpenAI plugins repository prevent breaking changes during updates?

The repository implements a multi-layered validation system that includes CI manifest validation, semantic versioning requirements, and runtime drift detection. Before any update reaches the marketplace, the POST /marketplace/apps/manifest/validate endpoint verifies schema compliance. During runtime, clients check the api_version field against installed SDKs and report drift warnings if incompatibilities are detected.

What is the difference between manifest version and API version in OpenAI plugins?

The manifest version (manifest_version) uses semantic versioning to track the overall plugin bundle state, including metadata and skill definitions. The API version (api_version) specifies the minimum SDK version required by the plugin code. While the manifest version changes with every plugin release, the API version only changes when the plugin adopts new SDK features or breaking changes.

How do Temporal-based plugins handle workflow updates without losing state?

Temporal plugins use worker versioning through the GetVersion API. When workflow logic changes, developers increment a version identifier in the code. The Temporal server compares this against running executions, routing existing workflows to the old logic while directing new executions to the updated code. This allows seamless updates without terminating active workflows.

Where should developers store version information in a Codex-plugin bundle?

All version metadata resides in .codex-plugin/plugin.json at the plugin root. This file must include manifest_version for the bundle version and api_version for SDK compatibility. Individual skills may contain additional version configurations, such as Temporal workflow constants or SDK-specific version pins in their respective configuration files.

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