GitHub Action Setup

patchworks create writes .github/workflows/patchworks.yaml with a nightly schedule, manual trigger, and the exact Patchworks action version that created it. The equivalent manual setup below uses the maintained v0 release so it is ready to copy today:

name: Patchworks

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * *"

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: patchworks-${{ github.repository }}
  cancel-in-progress: false

jobs:
  patchworks:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      # Use a GitHub App token or fine-grained PAT as PATCHWORKS_TOKEN when:
      # - the template is private and cross-repository (template Contents read),
      # - updates may change .github/workflows (Workflows write access), or
      # - Patchworks pull requests must trigger normal CI without approval
      #   (GITHUB_TOKEN-created runs are approval-gated).
      # The token also needs Contents and Pull requests write on this repository.
      - name: Update from template
        uses: ludicroushq/patchworks@v0
        with:
          token: ${{ secrets.PATCHWORKS_TOKEN }}

An undefined PATCHWORKS_TOKEN secret produces an empty input, so the action falls back to the job's GITHUB_TOKEN. The concurrency group prevents two scheduled or manual runs from updating the same repository at once.

What a run does

Before checkout, the action queries GitHub for an open pull request whose head is patchworks/update. If one exists, the action returns status=pull-request-open and stops. This protects human conflict resolutions from being replaced by a later scheduled run.

If that update branch exists without an open pull request, Patchworks reuses it only when its head exactly matches the head of the newest merged Patchworks pull request. Otherwise it stops before checkout and asks you to inspect, rename, or delete the branch deliberately. This prevents an orphaned branch or human commits from being overwritten.

With no open pull request, the action:

1. Classifies the effective token and, when using GITHUB_TOKEN, warns that it cannot verify the repository's Actions pull-request setting.
2. Checks out the base branch with full history and without persisting credentials.
3. Executes patchworks update --report <temporary-path>.
4. Reconciles the report with the real Git working tree, including unusual filenames, reject artifacts, and changed workflow files.
5. Uses peter-evans/create-pull-request to open a pull request containing all prepared changes and a current reject list. A conflicted update still opens a reviewable pull request.

The action does not touch the update branch while its pull request is open. Merge or close that pull request before asking Patchworks to prepare the next template commit.

Rewritten template history is not rebased automatically. Run the CLI locally, review the new history, and use patchworks update --rebase explicitly.

Version selection

The generated workflow pins the exact action release matching the Patchworks package that created it: uses receives the package's full v<semver> tag. It never emits a moving v0 reference. Upgrade that exact tag deliberately when adopting a new Patchworks release, or use a full commit SHA for the strongest immutable selection.

At any action revision, Patchworks reads its checked-in packages/patchworks/package.json and executes that exact npm package version. It never installs patchworks@latest. The patchworks-package input is reserved for testing an exact package or immutable pkg.pr.new build before release.

Permissions

The workflow needs:

permissions:
  contents: write
  pull-requests: write

When using GITHUB_TOKEN, also enable Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests. An organization policy may lock this repository setting. GITHUB_TOKEN does not have the Administration permission required to inspect that setting, so Patchworks reports permission-check=not-verifiable, continues with a warning, and leaves pull-request creation as the final authority.

When a custom token is required

GitHub does not let GITHUB_TOKEN push changes under .github/workflows, even when the job grants contents: write. Patchworks detects this case and stops before pull-request creation with the changed workflow paths listed.

Pull-request workflow runs created with a repository's GITHUB_TOKEN are approval-gated rather than normal unattended CI. If Patchworks pull requests must start the repository's checks without manual approval, authenticate the update with a GitHub App token or PAT instead.

Pass a GitHub App installation token or fine-grained personal access token through the action input:

- uses: ludicroushq/patchworks@v0
  with:
    token: ${{ secrets.PATCHWORKS_TOKEN }}

The token needs Contents and Pull requests write access to the child repository. Add Workflows write access when template updates can change workflow files. For a private template in another repository on the same GitHub host, it also needs Contents read access there. The action scopes authentication to github.server_url and safely rewrites same-host HTTPS, SCP-style git@host:path, and ssh://git@host/path template URLs for that token. URLs on other hosts use their own ambient Git credentials and never receive the token.

Inputs

Outputs

has-changes, has-rejects, had-conflicts, workflow-changes, and the pull-request number are emitted as GitHub Action output strings.

Change the schedule

GitHub cron schedules use UTC. For a weekly run at midnight Sunday UTC:

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * 0"