Local Sealing Rules

The .seal-actions.yml schema used by Local Sealing Rules under the Local deployment method.

A Local Sealing Rule is an entry in a .seal-actions.yml file checked into a repository. The Seal CLI in local mode reads the file at run time and substitutes sealed versions accordingly. For the rule model and how local rules relate to remote rules, see the Sealing Rules overview. This page covers the file format and the constraints specific to file-stored rules.

What local rules can express

Local rules are a strict subset of the four rule types:

• Project scope — always one specific Seal Project per file. The file is per-repository and the schema accepts exactly one project entry; multi-project files are not supported. A monorepo with multiple Seal Projects needs one .seal-actions.yml per project, in each project's own directory.

• Origin target — always a specific package at a specific version. There is no wildcard for "all packages" and no wildcard for "all versions of one package". Every entry names a package and a version explicitly.

• Substitute version — always a specific pinned -sp[N]. The safest-version option (the un-pinned default in the UI for remote rules) is not supported in the file: every use: value is a concrete version string.

If you need an all-packages rule, a tenant-wide rule, or an un-pinned safest-version rule for a Seal Project, that project must use the Remote deployment method and the rule must live on the platform.

When the file is read

The Seal CLI reads .seal-actions.yml from the repository root when it runs in local mode (the CLI fix mode the customer passes is local). The file is not read in remote mode, in all mode, or by any non-CLI deployment.

In source-control-connected Seal Projects, the Seal GitHub App can open pull requests that add or update entries in this file as new sealed versions become available. Merging the PR updates the file the CLI reads on the next build.

How local rules relate to remote rules

The Seal CLI consults one rule source per build, decided by the CLI fix mode:

• Local mode → only .seal-actions.yml is read; any remote rules configured for that Seal Project on the platform do not affect the build.

• Remote mode → only the platform's remote rules are read; .seal-actions.yml, even if present, does not affect the build.

The two sources do not stack and there is no precedence between them. A Seal Project that switches deployment methods later starts using the rule source for its new method on the next build.

File location and name

• Filename: .seal-actions.yml, exactly. No alternative spellings are accepted.

• Location: the repository root, alongside the dependency manifest.

• One file per repository, describing one Seal Project.

Schema

meta:
  schema-version: 0.1.0
  created-on: 2026-06-02T10:30:00Z
  cli-version: 1.4.2
projects:
  my-project:
    targets:
      - .
    manager:
      ecosystem: node
      name: yarn
      version: 1.22.19
      class: manifest
    overrides:
      ejs:
        2.7.4:
          use: 2.7.4-sp2
      lodash:
        4.17.20:
          use: 4.17.20-sp1

meta

Field	Required	Description
schema-version	yes	Schema version of the file. The current schema is 0.1.0. The CLI warns on minor differences and refuses to load a file whose major version is incompatible.
created-on	yes	ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SSZ) of when the file was generated. Refreshed by the CLI when it writes the file; informational.
cli-version	yes	The Seal CLI version that wrote the file. Informational; the CLI warns if it differs from the running CLI's version.

The meta section is auto-populated when the CLI generates the file. If you author the file by hand, fill these in once and let the CLI update them on subsequent writes.

projects

A map of Seal Project name to project section, with exactly one entry. The project name must match the Seal Project's name in the platform. A file with zero or more than one project entry is rejected at load time.

Each project section has:

Field	Required	Description
targets	yes	A list of paths within the repository the CLI scans. At minimum one entry. Use . for the repository root.
manager	yes	The package manager used by this project. See "manager" below.
overrides	no	The rule entries themselves. A two-level map: package name → version → substitute. Omit the field when no rules are active; an empty overrides: is also accepted.

manager

Field	Required	Description
ecosystem	yes	The ecosystem the project belongs to (for example, node, python, java).
name	yes	The specific package manager within the ecosystem (npm, yarn, pnpm, pip, poetry, maven, gradle, etc.).
version	no	The package manager version. Optional.
class	no	One of manifest, os, files, image. Defaults to manifest, the value used for application dependencies. The other values are for specialized fix modes (Seal OS, file-based scans, image scans).

overrides

Each entry is one Local Sealing Rule:

overrides:
  <package-name>:
    <origin-version>:
      use: <substitute-version>

• The outer key is the package name as the package manager identifies it (ejs, org.apache.commons:commons-text, etc.).

• The next-level key is the origin version (2.7.4).

• use is the substitute version — a specific -sp[N]. Required.

Multiple entries under one package are independent rules; listing ejs at both 2.7.4 and 3.0.1 produces two separate substitutions, one per origin version.

Behavior and edge cases

• Schema-version mismatches: minor-version differences produce a warning and proceed. Major-version differences halt the CLI run with an unsupported-schema-version error.

• Hand-editing vs CLI-managed: both work. The CLI rewrites the meta block on every write; if you hand-edit, expect those fields to change next time the CLI saves the file.

• Switching deployment methods: changing a Seal Project's deployment method to Remote means the .seal-actions.yml is no longer consulted. The file can be deleted on the switch, or left in place harmlessly until cleanup.

Related

• Sealing Rules overview: the rule model, the four rule types, and precedence.

• Remote Sealing Rules: the counterpart for Remote-mode Seal Projects.

• Choosing your deployment method: when Local is the right deployment method.

• The CLI fix mode: the mode under which .seal-actions.yml is read.

• Connecting GitHub: the source-control integration that can open PRs updating this file.