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

> Learn about plugin.lock.json within the OpenAI plugins repository. Understand its purpose in ensuring reproducible builds and runtime verification through exact version recording and integrity hashes.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: internals
- Published: 2026-06-27

---

**[`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.lock.json)** follows this structure, as seen in [`plugins/figma/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/figma/plugin.lock.json):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json).

2. **Regenerate the Lock** – Execute the Codex packaging command (e.g., `codex pack --plugin ./plugins/figma`) to rewrite **[`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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:

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

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

```bash

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json)** defines the plugin's configuration, metadata, and desired skill dependencies, **[`plugin.lock.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.