docs: replace custom GitHub Action with CI workflow guide

Author: elijahr

README.md

@@ -340,22 +340,9 @@ print(writer.write(header))
 
 Full documentation, guides, and API reference: [axiomantic.github.io/headerkit](https://axiomantic.github.io/headerkit/)
 
-## GitHub Action
+## CI Store Population
 
-headerkit includes a GitHub Action for populating the cache in CI.
-Add it to a workflow that triggers on header changes:
-
-```yaml
-- uses: axiomantic/headerkit@v0
-  with:
-    args: "include/mylib.h -w cffi --platform linux/amd64 --platform linux/arm64"
-    commit: "true"
-```
-
-This installs headerkit, runs `cache populate` with the specified
-arguments, and optionally commits the updated `.headerkit/` directory.
-
-See the [GitHub Action Guide](https://axiomantic.github.io/headerkit/guides/github-action/) for full usage, cibuildwheel integration, and multi-platform examples.
+headerkit's build backend populates `.headerkit/` during wheel builds. To keep the store updated across platforms in CI, see the [CI Store Population guide](https://axiomantic.github.io/headerkit/guides/github-action/).
 
 ## Development
 

action.yml

@@ -1,158 +1,159 @@
-# GitHub Action
+# CI Store Population
 
-headerkit ships a composite GitHub Action that populates the
-`.headerkit/` cache in CI. Use it to keep cache entries up to date
-whenever headers change, so downstream builds never need libclang.
+headerkit's PEP 517 build backend populates `.headerkit/` during wheel
+builds. To keep the store up to date across platforms, use a CI workflow
+that builds wheels in a matrix, collects artifacts, and opens a PR if
+anything changed. No custom action needed -- just standard GitHub Actions
+building blocks.
 
-## What it does
-
-The action runs three steps:
-
-1. Sets up Python (via `actions/setup-python`).
-2. Installs headerkit from PyPI.
-3. Runs `headerkit cache populate` with the arguments you provide.
+## How it works
 
-Optionally, it commits the updated `.headerkit/` directory back to the
-branch.
+The `.headerkit/` directory contains IR (parsed headers) and output
+(generated bindings) so that downstream builds work without libclang
+installed. This directory should be committed to your repository; it is
+not ephemeral cache.
 
-## Inputs
+The CI pattern has two jobs:
 
-| Input | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `headerkit-version` | no | latest | Pin a specific headerkit version (e.g., `0.15.0`) |
-| `python-version` | no | `3.12` | Python version for the runner |
-| `args` | no | `""` | Arguments passed to `headerkit cache populate` |
-| `commit` | no | `false` | Commit populated cache files after generation |
+1. **build** -- runs in a matrix across platforms, builds wheels, and
+   uploads the `.headerkit/` directory as an artifact.
+2. **update-store** -- downloads all artifacts into a single `.headerkit/`
+   directory and opens a PR if anything changed.
 
-## Basic usage
+## Example workflow
 
 ```yaml
-name: Populate headerkit cache
+name: Update headerkit store
 on:
   push:
+    branches: [main]
     paths:
       - "include/**/*.h"
+      - "pyproject.toml"
+  schedule:
+    - cron: "0 6 * * 1"  # weekly on Monday
 
 jobs:
-  populate:
-    runs-on: ubuntu-latest
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
 
-      - uses: axiomantic/headerkit@v0
+      - uses: actions/setup-python@v5
         with:
-          args: "include/mylib.h -w cffi --platform linux/amd64"
-          commit: "true"
-```
-
-This installs the latest headerkit, runs `cache populate` for the
-specified header and platform, and commits the result.
+          python-version: "3.12"
 
-## Pin a headerkit version
+      - name: Build wheel
+        run: pip install build && python -m build --wheel
 
-Lock the version to avoid surprises from new releases:
-
-```yaml
-- uses: axiomantic/headerkit@v0
-  with:
-    headerkit-version: "0.15.0"
-    args: "include/mylib.h -w cffi --cibuildwheel"
-```
+      - uses: actions/upload-artifact@v4
+        with:
+          name: headerkit-store-${{ matrix.os }}
+          path: .headerkit/
 
-## Usage with cibuildwheel
+  update-store:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
 
-If your project uses cibuildwheel, pass `--cibuildwheel` to auto-detect
-target platforms and Python versions from `[tool.cibuildwheel]` in
-`pyproject.toml`:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: headerkit-store-*
+          path: .headerkit/
+          merge-multiple: true
 
-```yaml
-- uses: axiomantic/headerkit@v0
-  with:
-    args: "--cibuildwheel"
-    commit: "true"
+      - uses: peter-evans/create-pull-request@v8
+        with:
+          commit-message: "chore: update headerkit store"
+          title: "chore: update headerkit store"
+          branch: headerkit/update-store
+          body: |
+            Automated update of `.headerkit/` store from CI matrix build.
+          labels: automated
 ```
 
-This reads the `build` and `skip` selectors to determine which CPython
-versions and Linux platforms to target.
-
-## Usage with multiple platforms
+## Using cibuildwheel
 
-Generate cache entries for specific platforms using `--platform`:
+If your project uses cibuildwheel, replace the build step:
 
 ```yaml
-- uses: axiomantic/headerkit@v0
-  with:
-    args: >-
-      include/mylib.h -w cffi
-      --platform linux/amd64
-      --platform linux/arm64
-    commit: "true"
-```
-
-For macOS and Windows targets, run the action on the matching runner
-OS instead of relying on Docker emulation:
-
-```yaml
-jobs:
-  populate-linux:
-    runs-on: ubuntu-latest
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - uses: axiomantic/headerkit@v0
+
+      - uses: actions/setup-python@v5
         with:
-          args: "include/mylib.h -w cffi --platform linux/amd64 --platform linux/arm64"
-          commit: "true"
+          python-version: "3.12"
 
-  populate-macos:
-    runs-on: macos-latest
-    needs: populate-linux
-    steps:
-      - uses: actions/checkout@v4
-      - uses: axiomantic/headerkit@v0
+      - name: Build wheels
+        run: pip install cibuildwheel && cibuildwheel --output-dir dist
+
+      - uses: actions/upload-artifact@v4
         with:
-          args: "include/mylib.h -w cffi"
-          commit: "true"
+          name: headerkit-store-${{ matrix.os }}
+          path: .headerkit/
 ```
 
-Note that when `commit: "true"` is used across multiple jobs, each job
-must pull the latest commit from the previous job to avoid conflicts.
-Use `needs:` to sequence them.
+The build backend populates `.headerkit/` as a side effect of each wheel
+build, so cibuildwheel produces store entries for every platform in the
+matrix automatically.
 
-## How it works
+## Configuration options
 
-The action is a [composite action](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)
-defined in `action.yml` at the repository root. It:
+### Customizing platforms
 
-1. Calls `actions/setup-python` with the requested Python version.
-2. Installs headerkit via pip. If `headerkit-version` is set, it pins
-   that exact version; otherwise it installs the latest release.
-3. Runs `headerkit cache populate` with your `args` value. The args
-   are passed through to the command as-is, so any flag that
-   `cache populate` accepts works here.
-4. If `commit` is `"true"`, it configures a bot git identity, stages
-   `.headerkit/`, and commits if there are changes. If the cache is
-   already up to date, the commit step is a no-op.
+Add or remove entries from `matrix.os` to match your target platforms:
 
-All input values are passed via environment variables (not shell
-interpolation) to prevent injection attacks.
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
+```
 
-## Triggering on header changes
+### Configuring the PR
 
-Use `paths` filters to run the action only when headers change:
+The `peter-evans/create-pull-request` action accepts many options for
+customizing the resulting pull request:
 
 ```yaml
-on:
-  push:
-    paths:
-      - "include/**/*.h"
-      - "vendor/**/*.h"
+- uses: peter-evans/create-pull-request@v8
+  with:
+    commit-message: "chore: update headerkit store"
+    title: "chore: update headerkit store"
+    branch: headerkit/update-store
+    labels: automated, dependencies
+    reviewers: your-username
+    draft: false
 ```
 
-This avoids unnecessary cache populate runs on unrelated commits.
+See the [create-pull-request documentation](https://github.com/peter-evans/create-pull-request)
+for the full list of inputs.
+
+### Running on schedule vs on push
+
+The example workflow triggers both on push (when headers change) and on a
+weekly schedule. Adjust to fit your project:
+
+- **On push with path filters** -- reacts to header changes immediately.
+- **On schedule** -- catches changes from dependency updates or toolchain
+  upgrades that affect generated output.
+- **Manual dispatch** -- add `workflow_dispatch:` to the `on:` block
+  to allow manual runs from the Actions tab.
 
 ## See also
 
 - [Cache Strategy Guide](cache.md) for cache layout, bypass flags, and
   multi-platform population details.
 - [Build Backend Guide](build-backend.md) for using headerkit as a
-  PEP 517 build backend with committed cache.
+  PEP 517 build backend with committed store.

docs/guides/github-action.md

@@ -79,7 +79,7 @@ nav:
     - Target Triples: design/target-triples.md
     - Cache System: guides/cache.md
     - Build Backend: guides/build-backend.md
-    - GitHub Action: guides/github-action.md
+    - CI Store Population: guides/github-action.md
     - Using CFFI Writer: guides/cffi.md
     - Writing Custom Backends: guides/custom-backends.md
     - Writing Custom Writers: guides/custom-writers.md