Plugin Version Management and Publishing: Best Practices for OpenAI Plugins

Use semantic versioning in .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 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, the "version" field must follow this format to ensure compatibility and clear communication of changes.

Version Field Requirements

In .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 using kebab-case. This requirement, documented in the specification at lines 52-53 of 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 and verifies required fields.

Running the Plugin Evaluator

The validation logic resides in 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:

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

Alternatively, execute the evaluation through npm if configured in your package.json:

npm run eval

Automated CI Checks

Configure your continuous integration pipeline to lint 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 – 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:

   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 – If registering in the Codex marketplace, add or update your entry with required policy fields:

   {
     "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).

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 file requires specific policy configurations. According to the specification in .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 at the plugin root and reference changes in commit messages.
• Unpublished assets – Verify that all files referenced in plugin.json (icons, logos, screenshots) exist in the repository before tagging.

Summary

• Maintain semantic versioning (MAJOR.MINOR.PATCH) in .codex-plugin/plugin.json according to the specification in .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 before publishing.
• Create Git tags in the format v<MAJOR>.<MINOR>.<PATCH> to establish reliable rollback points.
• Register marketplace entries in marketplace.json with required policy and category fields.
• Maintain a 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 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.

How do I validate my plugin before publishing?

Run the built-in evaluator located in 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 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 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 lines 98-106.

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