# Plugin Version Management and Publishing: Best Practices for OpenAI Plugins

> Learn best practices for OpenAI plugin version management and publishing. Use semantic versioning, validate with plugin-eval, and sync Git tags for smooth marketplace submission.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-06-16

---

**Use semantic versioning in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), validate with the `plugin-eval` test suite, and synchronize Git tags with version bumps before marketplace submission.**

Effective plugin version management and publishing in the OpenAI Plugins repository requires strict adherence to the manifest specification. The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file serves as the single source of truth for versioning and metadata, while the built-in evaluator ensures validation before any release reaches the Codex marketplace.

## Semantic Versioning in the Plugin Manifest

The OpenAI Plugins specification mandates **semantic versioning** (`MAJOR.MINOR.PATCH`) in the manifest file. According to [`.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), the `"version"` field must follow this format to ensure compatibility and clear communication of changes.

### Version Field Requirements

In [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), increment version numbers according to these rules:

- **MAJOR**: Breaking API changes that require user action
- **MINOR**: New backward-compatible features  
- **PATCH**: Bug fixes and minor improvements

The evaluator checks this field during validation to ensure it conforms to the `X.Y.Z` pattern.

### Folder Name Synchronization

The plugin directory name **must** match the `"name"` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) using kebab-case. This requirement, documented in the specification at lines 52-53 of [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md), prevents lookup mismatches during marketplace indexing. For example, a plugin named `"my-awesome-tool"` must reside in a folder named `my-awesome-tool`.

## Pre-Publishing Validation

Before publishing, you must validate the manifest against the schema. The repository includes a dedicated evaluator that parses [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and verifies required fields.

### Running the Plugin Evaluator

The validation logic resides in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js). This evaluator checks for proper JSON structure, required metadata fields, and semantic version formatting.

Run the evaluator locally before committing:

```bash
npx jest plugins/plugin-eval/tests/plugin-eval.test.js --runTestsByPath

```

Alternatively, execute the evaluation through npm if configured in your [`package.json`](https://github.com/openai/plugins/blob/main/package.json):

```bash
npm run eval

```

### Automated CI Checks

Configure your continuous integration pipeline to lint [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and run the evaluator automatically. This guarantees that every commit passes basic quality gates before reaching the marketplace. Abort builds on validation errors to prevent invalid manifests from entering the release cycle.

## Publishing Workflow

Follow these steps to publish a new version:

1. **Update [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – Bump the `"version"` field according to semantic versioning rules.

2. **Validate the manifest** – Run the evaluator to confirm the JSON parses correctly and contains all required fields.

3. **Commit and tag** – Create a Git tag matching the version:
   ```bash
   git add .codex-plugin/plugin.json
   git commit -m "chore: bump version to 1.3.0"
   git tag v1.3.0
   git push && git push --tags
   ```

4. **Update [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)** – If registering in the Codex marketplace, add or update your entry with required policy fields:
   ```json
   {
     "name": "my-plugin",
     "source": { "source": "local", "path": "./plugins/my-plugin" },
     "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
     "category": "Productivity"
   }
   ```

5. **Submit to marketplace** – Follow platform-specific publishing guidelines found in service-specific README files (e.g., [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md)).

6. **Verify post-publish** – Confirm the marketplace displays the correct version and all referenced assets (`composerIcon`, `logo`, `screenshots`) are accessible.

### Marketplace Registration

The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file requires specific policy configurations. 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) (lines 98-106), each entry must include `policy.installation`, `policy.authentication`, and a `category` classification. These fields control how users discover and install your plugin.

## Common Pitfalls and Mitigations

Avoid these frequent errors during plugin version management and publishing:

- **Forgetting version bumps** – Automate version increments using `npm version patch` or similar CLI tools in your CI pipeline.
- **Folder name mismatches** – Implement a pre-commit hook that verifies `basename(pluginRoot) === manifest.name`.
- **Invalid manifests** – Always run the `plugin-eval` validator locally before pushing to remote.
- **Missing changelogs** – Maintain a [`CHANGELOG.md`](https://github.com/openai/plugins/blob/main/CHANGELOG.md) at the plugin root and reference changes in commit messages.
- **Unpublished assets** – Verify that all files referenced in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) (icons, logos, screenshots) exist in the repository before tagging.

## Summary

- Maintain semantic versioning (`MAJOR.MINOR.PATCH`) in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) 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).
- Ensure the plugin folder name matches the manifest `"name"` field in kebab-case.
- Validate every change using the evaluator in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) before publishing.
- Create Git tags in the format `v<MAJOR>.<MINOR>.<PATCH>` to establish reliable rollback points.
- Register marketplace entries in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) with required `policy` and `category` fields.
- Maintain a [`CHANGELOG.md`](https://github.com/openai/plugins/blob/main/CHANGELOG.md) and verify all referenced assets exist before submission.

## Frequently Asked Questions

### What file controls plugin version management in OpenAI Plugins?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file controls version management. This manifest must reside in the `.codex-plugin` directory and contains the `"version"` field that follows semantic versioning rules, as defined in the specification at [`.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).

### How do I validate my plugin before publishing?

Run the built-in evaluator located in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js). Execute the test suite with `npx jest plugins/plugin-eval/tests/plugin-eval.test.js` to verify that your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) parses correctly and contains all required metadata fields.

### What versioning scheme does the OpenAI Plugins repository require?

The repository requires **semantic versioning** (`MAJOR.MINOR.PATCH`). Increment the major version for breaking changes, minor for new backward-compatible features, and patch for bug fixes. This standard is enforced by the evaluator and documented in the plugin JSON specification.

### Where do I register my plugin for the Codex marketplace?

Register your plugin in the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. Each entry must include the plugin name, source path, installation policy, authentication policy, and category classification according to the marketplace 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) lines 98-106.