# How to Version a Codex Plugin: Complete Guide to Semantic Versioning

> Learn how to version a Codex plugin using semantic versioning MAJOR.MINOR.PATCH. Update the version field in plugin.json and create a Git tag for clear releases.

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

---

**You version a Codex plugin by updating the `version` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) following semantic versioning (MAJOR.MINOR.PATCH), then committing the change and creating a matching Git tag.**

In the OpenAI plugins repository, the manifest file serves as the single source of truth for plugin identity and release management. The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file located in the `.codex-plugin/` directory contains the authoritative version string that the Codex plugin evaluator, marketplace UI, and CI pipelines all reference during validation and publishing workflows.

## Understanding the Codex Plugin Manifest

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is the canonical source for plugin metadata. According to the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), this JSON object must include a `version` property that follows strict semantic versioning rules.

The Zoom plugin provides a concrete example of this structure:

```json
{
  "name": "zoom",
  "version": "1.0.2",
  ...
}

```

All downstream tooling reads the version from this location exclusively. The evaluator script at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) validates that this field exists and conforms to expected formats before allowing publication.

## Semantic Versioning Requirements

Codex plugins follow **semantic versioning** (`MAJOR.MINOR.PATCH`) to communicate compatibility guarantees:

- **MAJOR** – Increment when introducing breaking API changes that require users to update their integration code.
- **MINOR** – Increment when adding backward-compatible features or enhancements.
- **PATCH** – Increment when making backward-compatible bug fixes or documentation updates.

The version string in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) must strictly adhere to this format without prefixes or suffixes (unless using pre-release labels specified in the plugin JSON spec).

## Step-by-Step Versioning Workflow

### 1. Choose the Appropriate Version Bump

Determine whether your changes warrant a major, minor, or patch increment based on the scope of modifications. Breaking changes to the plugin's API surface require a major version bump, while new capabilities that maintain backward compatibility warrant a minor bump.

### 2. Update the Manifest File

Edit [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to reflect the new version number. This is the only location where the version is stored; all other systems read from this file.

For automated updates using `sed`:

```bash
sed -i "s/\"version\": \".*\"/\"version\": \"1.1.0\"/" .codex-plugin/plugin.json

```

For Node.js-based plugins, you can leverage `npm version` which updates both [`package.json`](https://github.com/openai/plugins/blob/main/package.json) and writes the corresponding version to the Codex manifest:

```bash
npm version minor

```

### 3. Commit and Tag the Release

Create a Git commit with the manifest changes, then tag the commit with a version tag matching the manifest:

```bash
git commit -am "Bump to 1.1.0"
git tag v1.1.0

```

This tagging convention allows CI systems to locate the exact source code corresponding to any release.

### 4. Validate Before Publishing

Run the built-in evaluator to catch manifest errors before they reach production:

```bash
pnpm run plugin-eval

# Or directly:

node plugins/plugin-eval/src/evaluators/plugin.js

```

The validator checks for the presence of required fields including the `version` property and ensures proper formatting.

### 5. Update the Marketplace Entry (Optional)

If your plugin appears in the marketplace index, update the version field in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) to ensure the UI displays the latest version to users:

```json
{
  "plugins": [
    {
      "name": "zoom",
      "version": "1.1.0"
    }
  ]
}

```

## Automation Examples

### Node.js Version Bumping Script

Use this helper script to programmatically increment versions using the `semver` library:

```javascript
// bump-version.js – run from repo root
const fs = require('fs');
const path = require('path');
const semver = require('semver');

const manifestPath = path.join(__dirname, 'plugins/zoom/.codex-plugin/plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

const newVersion = semver.inc(manifest.version, 'patch'); // 'patch' | 'minor' | 'major'
manifest.version = newVersion;
fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));

console.log(`✅ Bumped to ${newVersion}`);

```

### Python Marketplace Updater

For updating the marketplace registry programmatically:

```python
import json, pathlib

marketplace_path = pathlib.Path('.agents/plugins/marketplace.json')
data = json.loads(marketplace_path.read_text())

# Find the entry and update its version

for p in data['plugins']:
    if p['name'] == 'zoom':
        p['version'] = '1.0.3'   # match the manifest version

        break

marketplace_path.write_text(json.dumps(data, indent=2))
print("Marketplace version updated.")

```

### CI Validation Pipeline

This GitHub Actions workflow verifies that Git tags match the manifest version before publishing:

```yaml
name: Release Plugin
on:
  push:
    tags: 'v*.*.*'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify manifest version matches tag
        run: |
          TAG=${GITHUB_REF#refs/tags/}
          VERSION=$(jq -r .version .codex-plugin/plugin.json)
          if [ "v$VERSION" != "$TAG" ]; then
            echo "Version mismatch! Manifest $VERSION vs Tag $TAG"
            exit 1
          fi
      - name: Publish
        run: ./scripts/publish.sh

```

## Key Files in the Versioning System

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – Primary manifest containing the authoritative version string.
- **[`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)** – Specification document defining version semantics and validation rules.
- **[`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js)** – Validation logic that checks version field presence and format.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** – Marketplace index for UI version display.

## Summary

- **Store versions exclusively in** [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) – this is the single source of truth referenced by all tools.
- **Follow semantic versioning** (MAJOR.MINOR.PATCH) to communicate compatibility guarantees to users.
- **Automate version bumps** using `npm version`, custom scripts, or CI pipelines to maintain consistency across Git tags and marketplace entries.
- **Validate changes** with the `plugin-eval` evaluator before publishing to catch malformed manifests early.
- **Tag releases** in Git with the `v` prefix matching the manifest version to enable reproducible builds.

## Frequently Asked Questions

### Where is the version number stored in a Codex plugin?

The version number is stored in the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file within the `version` field. This file serves as the single source of truth, and all tooling—including the evaluator in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) and the marketplace registry—reads the version from this location.

### What happens if my version doesn't follow semantic versioning?

The Codex plugin evaluator checks the version field during validation. While the system may accept non-semver strings, following semantic versioning is strongly recommended because the marketplace UI and downstream CI pipelines expect this format. Breaking these conventions may cause integration failures with automated release tools.

### How do I automate version bumps for my plugin?

Use the `npm version <major|minor|patch>` command for Node.js projects, which updates the manifest and creates Git tags automatically. Alternatively, implement a custom script using the `semver` library to increment versions in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), then commit the changes and push tags to trigger CI/CD pipelines.

### Should I update the marketplace.json file manually?

Yes, if your plugin is listed in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), you must manually update the version field there after bumping the manifest version. This ensures the marketplace displays the correct version to users. Some organizations automate this through the `plugin-creator` skill or CI scripts that sync the marketplace entry with the manifest.