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
binary The path to a patchula binary to run instead of installing a release, such as one built from source to try unreleased changes. 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 restored at the start of every run and saved at the end. With an App installation token, or the workflow’s own GITHUB_TOKEN, Git blobs, package catalogs, tool listings and lookup hints carry over to the next run’s freshly minted token when it lists exactly the same repositories; adding or removing a repository, or narrowing the token, starts a new cache. An installation that reaches more than a thousand repositories gets no carry-over. A personal token carries everything over as long as it stays the same token.

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. Releases older than the command key by their version. 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.