GitHub Action Overview

The Patch Pulse GitHub Action runs on a schedule, detects outdated dependencies using the Patch Pulse CLI, and opens one pull request per package (or package group) — keeping your dependency updates small, reviewable, and easy to revert.

Key features

• One PR per package (or group) — each update is independently reviewable and revertable
• Lockfile updates — automatically runs your package manager’s install after bumping versions, so the lockfile is always in sync
• Package grouping — define groups of related packages (e.g. all @tanstack/*) that update together in a single PR
• Monorepo-aware — bumps the package across every workspace it appears in, all in one PR
• Range-preserving — if you pin with ^, the PR writes ^new-version; exact pins stay exact
• Ignore list — exclude packages or glob patterns (@types/*) from ever getting a PR
• PR limit — caps the number of open patch-pulse PRs so your queue never gets overwhelming
• Breaking change risk labels — every PR includes a risk callout (NONE / LOW / HIGH) based on the update type
• Release notes links — the PR body links directly to GitHub releases for each updated package
• Respects closed PRs — if you close a PR without merging, the action won’t re-open it until you delete the branch
• Auto-merge — optionally enable GitHub’s native auto-merge so PRs squash-merge automatically once all required CI checks pass
• Assignees & reviewers — configure who gets assigned or requested for review on every opened PR
• Configurable commit prefix — use chore(deps):, deps:, or whatever fits your project’s commit convention
• No stale PR pile-up — one branch per group (patch-pulse/<name>), updated in place each run

How it works

1. The action runs npx patch-pulse --json --hide-clean in your repository
2. Outdated packages are filtered by your ignore list and grouped
3. For each group, a branch patch-pulse/<group-name> is created from your default branch
4. Version strings are bumped in every affected package.json, preserving the existing range prefix
5. The package manager’s install command runs to update the lockfile
6. The branch is pushed and a pull request is opened (or the existing one is updated)

Quick start

Add the following workflow to your repository at .github/workflows/patchpulse.yml:

name: PatchPulse Dependency Bot

on:
  schedule:
    - cron: '0 8 * * 1' # Every Monday at 08:00 UTC
  workflow_dispatch:

jobs:
  patch-pulse:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4 # remove if using npm / yarn
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - uses: barrymichaeldoyle/patch-pulse/packages/action@action/v0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Tip

Make sure your repository’s workflow permissions allow GitHub Actions to create pull requests. Go to Settings → Actions → General → Workflow permissions and enable Allow GitHub Actions to create and approve pull requests.

Example PR

For a minor update to a single package the action opens a PR like this:

chore(deps): update zod 3.22.0 → 3.24.0 (minor)

Breaking Change Risk: LOW

[!NOTE] Minor updates add backwards-compatible features. Review the release notes before merging.

Package	From	To	Type
zod	3.22.0	3.24.0	🟡 MINOR

Release Notes

• zod releases

See Configuration for grouping related packages, filtering update types, and enabling auto-merge.

Versioning

The action follows the same tag convention used by actions/checkout, actions/setup-node, and other official actions:

Ref	Behaviour
@action/v0	Recommended. Moving tag — always the latest v0.x release. You get new features and fixes automatically, but breaking changes (a v1) are opt-in.
@action/v0.1.0	Exact pin — nothing changes until you update the ref yourself. Use this in environments that require full reproducibility.
@main	Unreleased HEAD — avoid in production. Useful only for testing unreleased changes.

A new major tag will only be cut if a change would break existing workflow configurations. Additive changes (new inputs, new behaviour behind a flag) stay in the same major.