How to Handle Plugin Versioning in the OpenAI Plugins Repository

Plugin versioning in the OpenAI repository relies on semantic versioning declared in .codex-plugin/plugin.json and tracked via plugin.lock.json for reproducible marketplace builds.

The openai/plugins repository powers the Codex Plugin Marketplace, where every plugin release is governed by strict versioning rules. Understanding how to handle plugin versioning ensures that your integrations remain stable while allowing you to ship new features and bug fixes safely. This guide walks through the manifest structure, semantic versioning conventions, and the exact workflow used to publish updates.

Understanding the Plugin Manifest Structure

Every plugin in the repository is defined by a .codex-plugin/plugin.json manifest file. This file contains the mandatory metadata that the Codex Marketplace uses to identify, install, and update plugins.

The plugin.json Version Field

The manifest includes a required "version" field that represents the plugin’s runtime release version. For example, the Vercel plugin declares "version": "0.21.3" in plugins/vercel/.codex-plugin/plugin.json. This is the value that triggers update notifications in the marketplace when changed.

The plugin.lock.json Schema Version

Each plugin directory may contain a plugin.lock.json file that stores a "pluginVersion" field (e.g., "2.0.7" in the Figma plugin). This number represents the schema version of the lock file itself, not the plugin’s functional version. The lock file guarantees reproducible builds by pinning exact dependency states and is regenerated automatically during the publishing process.

Semantic Versioning Rules for OpenAI Plugins

The repository follows strict semantic versioning (MAJOR.MINOR.PATCH) to communicate compatibility guarantees to downstream users.

MAJOR Version Bumps (Breaking Changes)

Increment the MAJOR component when you introduce non-backward-compatible changes that require callers to adapt their integration. This includes renamed skill endpoints, altered request payloads, or removed command options.

MINOR Version Bumps (New Features)

Bump the MINOR version when adding functionality in a backward-compatible manner. Examples include new skills, additional optional parameters, or expanded documentation that does not alter existing API contracts.

PATCH Version Bumps (Bug Fixes)

Increase the PATCH number for bug fixes, security patches, or internal refactoring that preserves the public API surface. These changes should be transparent to existing integrations.

Step-by-Step Version Management Workflow

Follow this sequence when preparing a new release to ensure the marketplace correctly indexes your update.

1. Update the Manifest Version

Edit the "version" field in your plugin’s .codex-plugin/plugin.json file before committing. Choose the appropriate semantic level based on the nature of your changes.

{
  "name": "vercel",
  "version": "0.22.0",
  "description": "Build and deploy web apps and agents"
}

2. Regenerate the Lock File

Run the repository’s build script to update plugin.lock.json. This refreshes the "pluginVersion" field and pins the current dependency tree.

cd plugins/figma
./scripts/generate-lock.sh

The script automatically increments the lock file’s schema version if structural changes are detected (e.g., from "2.0.7" to "2.0.8").

3. Validate Before Publishing

Execute the marketplace validation script to verify that your new version complies with repository standards.

./validate-plugins.sh plugins/your-plugin-name

This checks for schema compliance, version conflicts, and backward compatibility violations.

Code Examples for Automated Version Bumping

For teams managing frequent releases, automate the PATCH increment using a Node.js helper:

// bump-patch.js
const fs = require('fs');
const path = process.argv[2];
const manifest = JSON.parse(fs.readFileSync(path, 'utf8'));

const [major, minor, patch] = manifest.version.split('.').map(Number);
manifest.version = `${major}.${minor}.${patch + 1}`;

fs.writeFileSync(path, JSON.stringify(manifest, null, 2));
console.log(`Bumped version to ${manifest.version}`);

Run the script from your plugin directory:

node bump-patch.js .codex-plugin/plugin.json

Summary

• Manifest versioning: Update "version" in .codex-plugin/plugin.json using semantic versioning (MAJOR.MINOR.PATCH).
• Lock file management: Regenerate plugin.lock.json to update the "pluginVersion" schema field and ensure reproducible builds.
• Compatibility rules: Reserve MAJOR bumps for breaking changes, MINOR for features, and PATCH for fixes.
• Validation: Always run validate-plugins.sh before submitting to catch versioning errors early.
• Source locations: Reference plugins/vercel/.codex-plugin/plugin.json for manifest examples and plugins/figma/plugin.lock.json for lock file structure.

Frequently Asked Questions

What is the difference between version and pluginVersion?

The "version" field in .codex-plugin/plugin.json declares the plugin’s functional release (e.g., 0.21.3), while the "pluginVersion" in plugin.lock.json tracks the lock file’s own schema version (e.g., 2.0.7). The marketplace uses the former to trigger client updates and the latter to verify build reproducibility.

When should I bump the MAJOR version?

Bump the MAJOR version when modifying existing skill signatures, changing request payload structures, or removing commands that would break existing integrations. According to the source code in plugins/vercel/.codex-plugin/plugin.json, any change requiring callers to update their integration code necessitates a MAJOR bump.

How do I validate a version bump locally?

Run the repository’s validate-plugins.sh script against your plugin directory. This tool checks for JSON schema compliance, semantic versioning format, and conflicts with existing marketplace versions before you publish.

Does the lock file affect runtime behavior?

No. The plugin.lock.json file is used exclusively by marketplace tooling to guarantee reproducible builds and verify artifact integrity. It does not alter runtime execution or API responses; those behaviors are governed solely by the "version" declared in the manifest.

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