Policy stores: file rules and limits

A policy store accepts only policy, schema, test suite, and test data files, and enforces size and count limits on every upload. The other files a policy repository ordinarily contains, such as CI configuration, documentation, and hidden files, are rejected or skipped according to the rules below.

Accepted files

Every file is checked against these rules when you upload:

Extensions

Only .json, .yaml, and .yml are accepted (the check is case-insensitive). Any other extension is unsupported: a README.md, Makefile, or .go file is not a store file.

Hidden paths

Any path with a component beginning with a dot is rejected, so .git/, .github/, and files such as .gitlab-ci.yml never enter the store.

Schemas

Files under _schemas/ must be JSON. A YAML file under _schemas/ is rejected.

Test data

Files under testdata/ must be named principals, resources, or auxdata (the spellings auxData and aux_data are also accepted), with any accepted extension. Any other filename under testdata/ is rejected.

Test suites

A file whose name ends in _test before the extension, such as album_test.yaml, is a test suite.

Policies

Every other accepted file is a policy. A test suite named tests.yaml is therefore read as a policy and rejected as malformed.

There is no .cerbosignore or ignore-file mechanism. A file is accepted or rejected by exactly the rules above.

Tests and the runtime bundle

Keep tests and test data in the store alongside the policies they exercise. Test suites and testdata/ fixtures are first-class store content, and Cerbos Hub runs them automatically.

  • Tests run when a deployment builds a bundle, not when you upload. Upload validates only that each file parses as a policy, schema, test suite, or fixture. The suites are executed later, when a deployment that references the store builds a bundle. A failing test blocks that bundle, and the previously built bundle stays active.

  • Test files never reach the runtime bundle. The bundle builder excludes test suites and testdata/, so including them in the store costs nothing at runtime and you do not need to strip them before uploading.

Uploading with the CLI

The cerbosctl hub store commands operate on a store’s files:

Command Purpose

upload-git

Apply the file changes between two commits of a local Git repository.

replace-files

Overwrite the whole store with the given set of files.

add-files

Add or update specific files.

delete-files

Remove specific files.

get-files

Download specific files.

list-files

List the files in the store.

download

Download the entire store.

upload-git works from committed history, not the working tree, so uncommitted edits are never uploaded. With no arguments it applies the changes between the commit recorded in the store’s current version and HEAD, and records the new commit details in the store. Use --from and --to to select an explicit commit range. When the store has no recorded commit details, upload-git replaces the store with the files at the target commit instead.

replace-files accepts a directory, a .zip archive, or - to read a zip from standard input:

cerbosctl hub store replace-files ./policies
cerbosctl hub store replace-files policies.zip
cat policies.zip | cerbosctl hub store replace-files -

Given a directory, replace-files zips the entire tree and uploads it, and the store classifies and filters the files on receipt. add-files instead filters as it walks the directory, dropping hidden and unsupported files before upload.

How uploads handle rejected files

The two bulk commands differ in how they treat a file that breaks a rule:

replace-files

A file with an unsupported extension, a hidden path, or a bad testdata/_schemas name is skipped and returned in an ignored-files list. The upload fails only when no usable files remain (no usable files). This makes it safe to point at a whole repository.

add-files

A rejected file fails the entire batch, and nothing is uploaded. The exception is the directory walk described above: hidden and unsupported files are dropped locally and never become part of the batch. Bad testdata and _schemas names are not checked locally, so they reach the API and do fail the batch.

A file that is otherwise valid but has invalid contents (a malformed policy, an invalid schema, or an invalid test suite, reported as test suite is invalid) is a hard failure in both commands. Content errors are never skipped.

Limits

Uploads are bounded by these limits:

Limit Value Applies to

Zipped upload size

15 MiB

replace-files

File size

5 MiB

every file

Total extracted size

50 MiB

a replace-files archive

Path length

1024 characters

every file path

Operations per batch

25

add-files, delete-files

Files per request

10

get-files