Skip to content

JSON report

patchula lookup --json and patchula run --json print one report for the whole batch. This page describes schema version 8.

{
"schemaVersion": 8,
"repositories": [{
"repository": "owner/repo",
"status": "complete",
"reason": null,
"packageFiles": [{
"path": "Cargo.toml",
"dependencies": [{
"manager": "cargo",
"name": "serde",
"package": "serde",
"current": {"value": "1", "version": "1.0.0", "digest": null},
"updates": [{
"newValue": "1", "newVersion": "1.1.0", "newDigest": null,
"updateType": "minor", "group": null
}]
}]
}]
}],
"stats": {"requests": 12, "notModified": 9, "cacheHits": 3, "extractionHits": 0, "lookups": 4, "phaseMicros": {}}
}

Readers should reject any other schemaVersion. Unknown fields are rejected too, so a new field means a new version. Version 8 added cooldown to a heldBack entry, naming the repository’s committed Cargo cooldown (hours and the config file that commits it) when the cooldown rather than waitHours holds the release, and to an updates entry, set only on a security fix proposed inside the cooldown so the lockfile run knows Cargo must allow the too-new release. Version 7 added the repository stale status for a repository that changed under the run, and stale as a pull request action status, with the actions object at its own version 3; version 6 split branch and pull request statuses, added the stale branch status and limited an image state to the ones in security, with the actions object at its own version 2; version 5 added a dependency’s registry; version 4 added the reason of a notice that is not a template update; version 3 added an image rebuild’s image check.

Field
repository owner/name
status complete, skipped, stale or error
reason Why it was skipped, raced or failed; null when complete
packageFiles Files with dependencies, each with a path and dependencies
warnings Optional. Files skipped, stale registry data and similar
skipped Optional. Declarations that are not read as versions, such as images built from variables: manager, path, line, value and reason
notices Optional. Newer versions that are reported and never proposed: a Copier template’s tags, which only copier update applies, and a release whose declaration cannot be rewritten to allow it without guessing, such as a Composer ^1 | ^2 needing 3.0. Each has manager, path, line, name, package, current, available, and compareUrl when the host has a compare page; the second kind also has a reason
lookupFailures Optional. Dependencies whose lookup failed; see below
tooling Optional. Tooling warnings that hold on a live run, one per rule: rule, optional detail (native for merge-without-ci, reviews-only or tagged-release), the branches it applies to, and optional silenced with the reason from warnings.quiet
defaultBranch, commit Optional. The branch and commit that were read

A complete repository with no package files had nothing the Count supports.

A stale repository is one that changed under the run — its default branch moved, a pull request it was reconciling changed, or its write inventory disagreed with what the run read — so the run stopped before writing against the stale view rather than report a failure. Only a real run reports it: the report carries actions and is never a dry run. The server runs the repository again, and run exits 5 when a repository went stale and none errored.

Each entry in lookupFailures is a dependency whose registry lookup failed, so its updates are unknown. A repository with lookup failures is still complete, and the failure is not repeated in warnings.

"lookupFailures": [{
"manager": "npm",
"path": "package.json",
"name": "is-number",
"package": "is-number",
"datasource": "npm",
"kind": "network",
"message": "HTTP 503"
}]
Field
manager, path, name, package The dependency, as in packageFiles
datasource Where it was looked up, such as npm, docker or github-tags
kind network (unreachable, or a 5xx answer), auth (401, 403 or 407), not-found, rate-limit, parse (an answer the Count could not read) or other
message The error in words

A failed digest lookup, such as an image tag whose digest could not be read, is a lookup failure too. Declarations in skipped and dependencies a rule ignores are never looked up, so they never fail. lookup and apply exit 4 when this list is not empty.

Field
manager The manager name used in configuration, such as npm or cargo
name The name in the manifest
package The registry identity; differs from name for aliases
registry Optional. The registry the package was looked up in, when it is not the source’s public one
occurrence Optional. Tells apart the same name declared more than once in a file
current.value The text in the manifest, such as ^1.2
current.version The resolved version, or null when unknown
current.digest The pinned digest, or null
updates Proposed updates, in no particular order
metadata Optional. See below
Field
newValue, newVersion, newDigest The target; at least one is set. A null newValue with a newVersion is a lockfile-only update: only a lockfile changes. For a direct dependency that is a release its declaration already allows; a transitive package, which has no declaration, moves the same way
updateType major, minor, patch, digest or pin
group The group name from configuration, or null
policy Optional. The policy that applies: versions, wait, windows, merge, labels. waitHours is the effective wait: a committed Cargo cooldown is already folded in
releaseAge Optional. publishedAt and the evaluatedAt it was judged against
fixes Optional. IDs of the current version’s advisories that the target no longer has
cooldown Optional. On a security fix, the committed Cargo cooldown the target may sit inside: hours and the config file. The lockfile run’s Cargo must allow the too-new release for this update
image Optional. For a pinned image’s new digest, the SBOM comparison: state, the compared platforms, the sboms read (digest, source, generator), os, packages, the fixed advisories with their package, old and new versions and platforms, introduced advisory IDs (most severe first), introducedDetails (OSV’s records for up to five of them), detail and silenced
Field
source, kinds Where the dependency came from and its kinds, such as devDependencies, or transitive for a vulnerable package only a lockfile records
locations Byte offsets, line, column and a pointer into the file
resolution How current.version was found: declared, lockfile, pinned-commit, floating-ref, release-line (an installed pin, such as a .tool-versions or .nvmrc version) or supported-range (a runtime constraint such as engines.node). lockfile covers every manager whose lockfile recorded the resolved version — npm, Bun, Cargo, Bundler, Composer, Pyproject, Go (a require version in go.mod is the version Go’s resolution recorded) and Terraform providers
heldBack Updates waiting on release age, per update type, with when they become eligible. An entry’s optional cooldown (hours, file) names a committed Cargo cooldown holding the release, in which case eligibleAt follows it and the dashboard offers no early-create box
lookup When the lookup ran, whether a stored catalog view was reused (catalog with fetchedAt and reused), disabled update types, and versions rejected as deprecated or yanked
tagDigests For GitHub Actions, the commit each proposed tag points at
image Optional. For a pinned image, the current digest’s warning state, in the same shape as an update’s image
advisories Optional. OSV advisories affecting the current version: id, aliases (CVE IDs among them), severity, summary, url and fixedIn, the lowest fixed release above the current one
stale Registry data used past its freshness because the registry was rate-limited, with the time it was fetched
credentialed Optional, true when a request made to look the dependency up, read its digests or read its image carried an operator registry’s credentials or a registry account’s token, directly or through a mirror; such a dependency’s lookup data is withheld from the repository API

run --json adds an actions object. lookup leaves it out.

"actions": {
"schemaVersion": 3,
"dryRun": true,
"branches": [{
"repository": "owner/repo",
"branch": "patchula/example-major-0123456789abcdef",
"baseCommit": "…",
"status": "planned",
"reason": "would create branch",
"message": "chore(deps): update example to 2.0.0",
"previousCommit": null,
"commit": null,
"verified": null,
"lockfilePending": false,
"files": [{"path": "mise.toml", "blobSha": "…", "diff": "--- a/mise.toml\n+++ b/mise.toml\n…"}]
}],
"pullRequests": [{
"repository": "owner/repo",
"branch": "patchula/example-major-0123456789abcdef",
"number": null,
"url": null,
"status": "planned",
"reason": null
}]
}

A branch’s status is one of planned, created, updated, rebased, unchanged, merged, deleted, skipped, stale, protected and error. stale means the default branch changed or moved after the Count read it, so nothing was written; the server runs the repository again. A pull request’s status is one of planned, created, updated, unchanged, closed, merged, skipped, stale, protected and error; stale means a publish race — the PR changed under the run, or its head did not show the published commit — so a rerun retries it. A dry run never reports a write (created, updated, rebased, closed, merged or deleted) and has no commit. A published branch has its commit and verified: true.

skipped, stale, protected and error always carry a reason. A protected or error action makes its repository an error, and the CLI exits with 1.

blobSha is the Git blob SHA of the new file, and diff is a unified diff against the base commit.