> For the complete documentation index, see [llms.txt](https://docs.sealsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealsecurity.io/using-platform/sealing-rules/local-rules.md).

# Local Sealing Rules

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](/using-platform/sealing-rules.md). 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](/using-platform/sealing-rules.md#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](/setup-apps-os/cli-in-cicd/cli-fix-mode.md) 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](/discovering/connecting-source-control/github.md) 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

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

```yaml
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](/using-platform/sealing-rules.md): the rule model, the four rule types, and precedence.
* [Remote Sealing Rules](/using-platform/sealing-rules/remote-rules.md): the counterpart for Remote-mode Seal Projects.
* [Choosing your deployment method](/setup-apps-os/choosing-deployment-method.md): when Local is the right deployment method.
* [The CLI fix mode](/setup-apps-os/cli-in-cicd/cli-fix-mode.md): the mode under which `.seal-actions.yml` is read.
* [Connecting GitHub](/discovering/connecting-source-control/github.md): the source-control integration that can open PRs updating this file.