# GitHub Actions

> Run Count Patchula on a schedule with the GitHub Action, for one repository or a whole organization, and the action's inputs.

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](https://count-patchula.sweepy.dev/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](https://count-patchula.sweepy.dev/guide/server/) instead.

> **Use a GitHub App token**
>
> Both setups use a GitHub App installation token. Pull requests opened with a workflow’s own `GITHUB_TOKEN` do not trigger other workflows, so your checks would never run on them and auto-merge would wait forever. The App needs the permissions listed under [creating the App](https://count-patchula.sweepy.dev/guide/server/#create-the-github-app).

## One repository

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

`.github/workflows/patchula.yml`

```yaml
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 }}
```

## A whole organization

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`

```yaml
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`

```pkl
amends "PatchulaConfig.pkl"
```

Policy files amend `PatchulaConfig.pkl` like any config, and the Count supplies it. See [sharing policy](https://count-patchula.sweepy.dev/guide/configuration/#sharing-policy-across-repositories) to build these files on one organization module.

## Inputs

| 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](https://count-patchula.sweepy.dev/reference/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.

> **Public repositories**
>
> The saved cache holds data from every repository the token reaches, private ones included, and a pull request from a fork can restore a public repository’s cache. So in a public repository the action saves the cache only when the token is an installation token that reaches that repository alone, such as the one-repository setup above or `GITHUB_TOKEN`. Run an organization-wide token from a private runner repository. A run that cannot save says so in a notice and still works, just without the cache. If an older release of the action already saved a cache in a public repository with a wider token, delete those caches (`gh cache delete --all`).

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`](https://count-patchula.sweepy.dev/guide/managers/#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.
