Patch Patrol

Patch Patrol is an interactive CLI for finding advisory-driven package updates across GitHub repositories, then optionally creating update pull requests.

Requirements

• Node.js 20+
• GitHub CLI authenticated with gh auth login
• To create PRs: permission to dispatch workflows in humaan/patch-patrol

Run

Run the published CLI directly:

pnpx @humaan/patch-patrol

The installed version is shown in the CLI banner. Use patch-patrol --version to print it directly. When a newer release is available, the interactive CLI shows a non-blocking update notice.

Interactive Flow

The CLI will guide you through:

1. Entering a GitHub owner, GitHub repo, or GitHub URL.
2. Choosing an advisory rule.
3. Choosing which bump levels to include.
4. Choosing whether to include matching open Patch Patrol PRs.
5. Reviewing affected projects.
6. Deciding whether to stop after the scan or create or update pull requests.
7. Selecting which projects should receive update branches and pull requests.

Use arrow keys to move through prompts, spacebar to toggle multiselect items, and enter to continue.

If you choose to create PRs, Patch Patrol dispatches a GitHub Actions workflow for each selected repository. The workflow uses the Patch Patrol GitHub App to create an advisory-specific branch, re-check affected packages, update package.json, refresh the lockfile, commit the change, push the branch, and open a pull request.

Pass --update-existing (or opt in during the guided flow) to scan matching open advisory PR branches as well as repository base branches. Existing PR updates append a new commit without rebasing or replacing prior work, verify the scanned head SHA before publishing, and refresh the generated PR title and managed body section. Repositories with archived status are skipped.

PRs and commits are created by the App bot. The person dispatching the workflow is added as a commit co-author and identified in the PR body. The most active GitHub-linked contributor across the repository's latest 50 commits is requested as a reviewer; if those commits have no linked contributor, no reviewer is requested.

PR titles use the Conventional Commits format. Advisory prTitle values that already follow it are used as-is; other titles are prefixed with fix(deps): when creating or updating a PR.

GitHub App Setup

PR creation requires a GitHub App installed on each target repository with these repository permissions:

• Contents: Read and write
• Pull requests: Read and write

Configure these Actions values for the humaan/patch-patrol repository:

• Organization or repository variable PATCH_PATROL_APP_ID: the GitHub App ID
• Organization or repository secret PATCH_PATROL_APP_PRIVATE_KEY: the complete App private key PEM

Restrict organization-level values to the Patch Patrol repository. The workflow exchanges the private key for a short-lived token scoped to one target repository; neither credential is included in the npm package or sent to the local CLI.

Create a patch-patrol-production Actions environment and restrict its deployment branches to main. The PR workflow is bound to this environment so workflows dispatched from untrusted branches cannot access the App private key. Protect changes to .github/workflows/** with required review.

Client organization owners must install the public-installable App on the repositories Patch Patrol should update.

Safety

• Scans read package.json files through the GitHub API.
• PR workflows are dispatched only after you opt in and select repos.
• Repos are patched in temporary checkouts, not in your local working tree.
• Lockfiles are generated on a read-only preparation runner. A separate clean runner independently validates the prepared manifests and lockfiles before minting a repository-scoped write token and publishing the PR.

Contributing Advisories

Advisories live in advisories/*.json, but advisory consumption is decoupled from the published package. The published CLI loads advisory rules from this repo's main branch, so the repo can receive new advisories without waiting for an npm publish.

Advisory files use human-readable rule IDs and publishedAt dates so the CLI can show the newest advisories first and select the first one by default. Technical identifiers such as GHSA and CVE IDs live in each rule's metadata and are displayed as secondary CLI info.

Package rules can declare exact or wildcard package names in sync. When an affected package triggers an update, Patch Patrol updates any matching direct dependencies in that repository to the same target version, keeping coordinated package families on one release train without flagging companion-only projects.

Rules can also declare conditional compatibility families. These activate only when required packages are present at specified current or projected versions, raise the primary package to the minimum compatible version for its release line, and align directly installed sibling packages to that primary version. Required compatibility updates are not suppressed by bump-level filters.

An affected range can define an optional Markdown prBody with package-specific upgrade or migration guidance. Patch Patrol includes guidance only when that range directly matches a dependency in the repository and deduplicates it across monorepo manifests. Synchronized companion updates do not add guidance by themselves.

To add an advisory:

1. Use the adding-advisories agent skill with the security advisory URL, GHSA, CVE, changelog, or affected-version notice.
2. Open a pull request that adds the new advisory JSON file.
3. Once the PR is merged to main, the advisory becomes available to everyone using the published CLI with the default advisory source.

Development

pnpm install
pnpm start

The selected advisory rule is serialized into the workflow dispatch, so the runner applies the exact rule reviewed by the operator rather than reloading a mutable source.