# How to Handle Plugin Versioning in the OpenAI Plugins Repository

> Learn to handle plugin versioning in the OpenAI Plugins repository using semantic versioning and plugin lock files for reproducible builds.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Plugin versioning in the OpenAI repository relies on semantic versioning declared in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and tracked via [`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file before committing. Choose the appropriate semantic level based on the nature of your changes.

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugin.lock.json). This refreshes the `"pluginVersion"` field and pins the current dependency tree.

```bash
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.

```bash
./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:

```javascript
// 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:

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

```

## Summary

- **Manifest versioning**: Update `"version"` in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) using semantic versioning (MAJOR.MINOR.PATCH).
- **Lock file management**: Regenerate [`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/validate-plugins.sh) before submitting to catch versioning errors early.
- **Source locations**: Reference [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json) for manifest examples and [`plugins/figma/plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) declares the plugin’s functional release (e.g., `0.21.3`), while the `"pluginVersion"` in [`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.