Understanding plugin.lock.json: Purpose and Management in OpenAI Plugins

plugin.lock.json is a deterministic lock file that records exact skill versions, source Git references, and SHA-256 integrity hashes to ensure reproducible builds and runtime verification for Codex plugins.

Managing dependencies in the openai/plugins repository requires precise tracking of external skills and their cryptographic fingerprints. The plugin.lock.json file serves as the immutable record of exactly which code ships with a plugin, preventing unexpected changes when source repositories evolve. Generated automatically by the Codex Plugin Pack tooling, this file is committed alongside plugin source code to create auditable, tamper-proof deployments.

What Is plugin.lock.json?

In the openai/plugins repository, plugin.lock.json functions as a deterministic dependency lock for individual plugins such as those found in plugins/figma/ or plugins/notion/. When the Codex Plugin Pack tool processes a plugin, it inventories every skill intended for distribution, captures the exact Git repository and commit reference, and computes a cryptographic hash of the vendored content.

This file differs from the plugin manifest (plugin.json) by focusing exclusively on build reproducibility and content verification rather than configuration. The lock file guarantees that checking out a specific plugin version always yields identical skill content, regardless of updates made to the original upstream repositories.

Three Core Purposes of plugin.lock.json

The lock file fulfills critical requirements for secure, maintainable plugin distribution.

Reproducible Builds

Each skill entry in plugin.lock.json pins the source to a specific Git reference ("ref": "c207989386b30063bcecaf6b1977d761b244732e"). This immutability ensures that building the plugin today produces exactly the same artifacts as building it tomorrow, even if the upstream skill repository has moved forward. The vendored path ("vendoredPath") specifies precisely where the skill resides within the plugin package.

Integrity Verification

Every locked skill includes an integrity field containing a SHA-256 hash prefix (e.g., "sha256-ed5fbc2887dedc0924d798324433d4c2173a235d10d4115ef88d86e54a0d6aae"). At runtime, the plugin loader computes the hash of the vendored skill files and compares it against this recorded value, immediately detecting tampering, corruption, or unauthorized modifications.

Dependency Tracking

The lock file provides complete transparency into third-party code dependencies. Each entry specifies the skill ID, its location within the plugin bundle, and the originating source repository ("source": {"type": "github", "repo": "figma/mcp-server-guide"}). This visibility enables security reviewers and CI pipelines to audit exactly which external code executes within the plugin environment.

File Structure and Schema

A typical plugin.lock.json follows this structure, as seen in plugins/figma/plugin.lock.json:

{
  "lockVersion": 1,
  "pluginId": "com.openai.figma",
  "pluginVersion": "2.0.7",
  "generatedBy": "codex plugin pack (draft)",
  "generatedAt": "2026-04-07T17:15:42Z",
  "skills": [
    {
      "id": "figma-code-connect",
      "vendoredPath": "skills/figma-code-connect-components",
      "source": {
        "type": "github",
        "repo": "figma/mcp-server-guide",
        "path": "skills/figma-code-connect",
        "ref": "500e8738438ed1204eaf23e61280d872f47534fd"
      },
      "integrity": "sha256-ed5fbc2887dedc0924d798324433d4c2173a235d10d4115ef88d86e54a0d6aae"
    }
  ]
}

Key fields include:

• lockVersion – Schema version (currently 1).
• pluginId / pluginVersion – Identifiers for the parent plugin.
• generatedBy / generatedAt – Metadata tracking which tool created the lock and when.
• skills – Array of locked dependencies, each containing id, vendoredPath, source (with ref), and integrity.

Management Workflow

Maintaining plugin.lock.json follows a standardized lifecycle:

1. Modify Skill References – Add or update skills in the plugin's skills/ directory or adjust references in plugin.json.

2. Regenerate the Lock – Execute the Codex packaging command (e.g., codex pack --plugin ./plugins/figma) to rewrite plugin.lock.json with fresh hashes and updated Git references.

3. Commit Changes – Commit the updated lock file alongside source changes. Because the file is source-controlled, pull requests reveal exactly which skill versions changed.

4. CI Verification – Automated pipelines run verification scripts that re-compute SHA-256 hashes for all vendored skills and abort builds if any computed hash differs from the locked value.

5. Avoid Manual Edits – Never hand-edit the lock file, as this risks breaking the cryptographic verification. Always modify skill sources and regenerate through the tooling.

Implementation Examples

Reading the Lock File

Load and enumerate locked skills using Node.js:

import { readFileSync } from "fs";

const lock = JSON.parse(
  readFileSync("./plugins/figma/plugin.lock.json", "utf-8")
);

console.log(`Plugin ${lock.pluginId} v${lock.pluginVersion}`);
lock.skills.forEach((skill) => {
  console.log(`- Skill: ${skill.id} at ${skill.vendoredPath}`);
});

Verifying Skill Integrity

Implement runtime hash verification to detect corruption:

import { readFileSync } from "fs";
import crypto from "crypto";

function verifySkill(skill) {
  const filePath = `./plugins/figma/${skill.vendoredPath}`;
  const data = readFileSync(filePath);
  const hash = crypto.createHash("sha256").update(data).digest("hex");
  const expected = skill.integrity.split("-")[1];
  return hash === expected;
}

// Verify all skills
const allValid = lock.skills.every(verifySkill);
console.log(`Integrity check: ${allValid ? "PASSED" : "FAILED"}`);

Regenerating the Lock File

Update the lock after modifying skill dependencies:

# Generate fresh lock file

codex pack --plugin ./plugins/figma

# Commit the deterministic output

git add plugins/figma/plugin.lock.json
git commit -m "Refresh lock after updating figma-code-connect skill"

Summary

• plugin.lock.json is a deterministic dependency lock that pins skills to exact Git references and SHA-256 hashes.
• The file ensures reproducible builds, enables runtime integrity verification, and provides transparent dependency tracking.
• Located in plugin directories (e.g., plugins/figma/plugin.lock.json), it is generated automatically by the Codex Plugin Pack tool and should never be manually edited.
• Management involves updating skill sources, running codex pack, and committing the resulting changes for CI verification.

Frequently Asked Questions

What happens if I manually edit plugin.lock.json?

Hand-editing plugin.lock.json breaks the cryptographic chain of trust. If the hash in the file no longer matches the actual content of the vendored skill, runtime verification will fail, causing the plugin loader to reject the package. Always modify skill sources and regenerate the lock through the Codex tooling.

How does plugin.lock.json differ from plugin.json?

While plugin.json defines the plugin's configuration, metadata, and desired skill dependencies, plugin.lock.json captures the exact resolved state of those dependencies including specific Git commit refs and integrity hashes. The manifest describes intent; the lock file guarantees implementation.

Can I use plugin.lock.json to audit third-party dependencies?

Yes. Each skill entry includes the source repository (repo), path within that repository, and exact commit reference (ref), making it trivial to inspect upstream code. The integrity field further ensures that the vendored copy matches the original source exactly, preventing supply-chain tampering.

What triggers a regeneration of plugin.lock.json?

The lock regenerates whenever you run the Codex packaging command after modifying skill references in plugin.json or updating files in the plugin's skills/ directory. CI pipelines can also trigger regeneration to ensure the lock stays synchronized with the manifest before deployment.

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