Skip to content

Getting started

This page takes one repository to its first update pull requests. You need a GitHub token and mise.

The fastest way is to give a coding agent in your repository this prompt:

Fetch https://raw.githubusercontent.com/sweepies/count-patchula/main/docs/agent-setup.md and follow its instructions to set up Count Patchula for this repository.

The agent checks for a Renovate config to migrate, asks how you want to run the Count, and sets him up. It asks before each decision and never asks for secrets. The steps below do the same by hand.

An agent reading these docs can start from llms.txt, which lists every page. Each page is also served as Markdown to a request with Accept: text/markdown, or at its URL followed by index.md.

  1. Terminal window
    mise use -g --minimum-release-age 0 packslip:sweepies/count-patchula
    patchula --version

    mise verifies the download against the release’s signed manifest. Other options are under installation.

  2. The Count only visits repositories that invite him. Commit a patchula.pkl at the repository root:

    patchula.pkl
    amends "PatchulaConfig.pkl"

    That is a complete config; everything comes from the schema’s defaults: every manager, exact pins (ranges kept for Cargo, pyproject.toml, Bundler and Composer, whose lockfiles hold the version; npm and Bun stay exact), digest pins for actions and images, a 24-hour release-age wait, one PR per update with at most ten ordinary ones open at once (security fixes are not held back by that limit), a dependency dashboard issue, and no auto-merge except for reference data such as CA bundles.

  3. Export PATCHULA_TOKEN (or GITHUB_TOKEN or GH_TOKEN). With none set, the Count uses a signed-in GitHub CLI’s token.

    • lookup and dry runs need any token that can read the repository.
    • Real runs need a GitHub App installation token so GitHub signs the commits; the App’s permissions are listed with the server.

    The GitHub App server can mint installation tokens itself.

  4. Terminal window
    patchula lookup --json acme/my-app > report.json
    patchula run --dry-run acme/my-app

    lookup lists each repository’s updates, known vulnerabilities, failed lookups and notices, with the counts first; --json writes the JSON report instead. run --dry-run prints the branches and diffs it would publish, without touching GitHub.

    -v adds request counts and phase timings.

  5. Terminal window
    patchula run acme/my-app

    The first run opens one PR per update, up to ten ordinary ones at once (security fixes are exempt from that limit), and a Dependency Dashboard issue that lists the rest. Lockfiles are regenerated with the real tools, which mise installs on first use. A repeat run on an unchanged repository costs one GraphQL query.

    With no repository named, commands use this checkout; see working tree or GitHub.

    To have the updates written into your checkout instead of opened as PRs, run patchula apply there, or pick them one by one in the terminal UI.

    To run him on a schedule, use the GitHub Action.

The recommended way to run the Count is the GitHub App server. It keeps caches warm, batches many repositories together, and acts on webhooks, so a ticked checkbox is handled straight away rather than at the next scheduled run. It idles most of the time, so usage-billed hosts such as Railway are cheap.