Skip to content

GitHub Actions

The repository is also a GitHub Action. It installs the Count with mise, keeps his cache between runs, and runs patchula run. A repository is updated when it invites him with a patchula.pkl (see getting started), or when an organization runner supplies its config with --config-dir.

For a handful of repositories this is the simplest setup. For more, or for PR checkboxes that act straight away, run the GitHub App server instead.

The workflow lives in the repository it updates, and the token covers only that repository.

.github/workflows/patchula.yml
name: Count Patchula
on:
schedule:
- cron: "17 3 * * *"
workflow_dispatch:
permissions: {}
concurrency:
group: patchula
cancel-in-progress: false
jobs:
patchula:
runs-on: ubuntu-latest
steps:
- uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
id: app
with:
client-id: ${{ vars.PATCHULA_CLIENT_ID }}
private-key: ${{ secrets.PATCHULA_APP_PRIVATE_KEY }}
- uses: sweepies/count-patchula@v0.9.0
with:
token: ${{ steps.app.outputs.token }}

One dedicated repository, such as my-org/patchula-runner, runs the Count for every repository the App is installed on. Install the App on the organization with access to the repositories you want updated; the runner repository needs no access of its own. Shared policy can live in the runner repository and be passed with --config-dir.

my-org/patchula-runner/.github/workflows/patchula.yml
name: Count Patchula
on:
schedule:
- cron: "17 3 * * *"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: patchula
cancel-in-progress: false
jobs:
patchula:
runs-on: ubuntu-latest
steps:
# Only needed for the policy directory below.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
id: app
with:
client-id: ${{ vars.PATCHULA_CLIENT_ID }}
private-key: ${{ secrets.PATCHULA_APP_PRIVATE_KEY }}
# Every repository the App is installed on in this organization.
owner: ${{ github.repository_owner }}
- uses: sweepies/count-patchula@v0.9.0
with:
token: ${{ steps.app.outputs.token }}
all-repos: "true"
# policy/<repo>.pkl or policy/<owner>/<repo>.pkl overrides a
# repository's own config.
args: --config-dir policy

--config-dir is optional. Without it, each repository is configured by its own patchula.pkl, and repositories without one are skipped. With it, a file in the directory takes the place of that repository’s config, so the runner can opt repositories in without committing to them:

my-org/patchula-runner/policy/my-app.pkl
amends "PatchulaConfig.pkl"

Policy files amend PatchulaConfig.pkl like any config, and the Count supplies it. See sharing policy to build these files on one organization module.

Input Default
token Required. The token the Count reads and writes with
repositories this repository owner/repo names, separated by spaces or newlines
all-repos false Every repository the token can reach
dry-run false Print planned branches and diffs without writing
version the action’s version, or the latest release when the action is not used at a release tag The Count version to install, such as 0.9.0; 0.9.0 or later
binary The path to a patchula binary to run instead of installing a release, such as one built from source to try unreleased changes; 0.9.0 or later. Overrides version
settings The path to an operator settings file, for HTTP limits and other operator settings. The action does not check out your repository, so add actions/checkout before it when the file lives there. Empty falls back to PATCHULA_SETTINGS, then ~/.config/patchula/settings.pkl, then the defaults
args Extra patchula run arguments, such as --config-dir policy

The cache, with HTTP validators, write receipts and the lockfile tools, is saved after every run and restored on the next, so later runs are much faster than the first. Entries are keyed by the cache schema the binary reads (patchula cache schema), so moving to a release with a new schema, or back to an older one, starts from a cold cache instead of failing on a database it cannot read.

The action runs Count Patchula 0.9.0 or later, the first release with patchula cache schema. Given an older version or binary, it fails the step with an error naming the binary rather than running it.

Where a repository keeps .github/workflows/actions.lock, the lockfile tool authenticates with the token the run was given — the token input’s token — scoped to the repository when the App can mint one.

A run where a repository changed underneath it — a push moved the default branch while the Count was publishing, say — stops rather than write against the stale view and patchula run exits 5. The action fails the step on that exit, so the race shows as a failed workflow run instead of a green run that wrote nothing; the next scheduled run retries the repository.