diff --git a/.github/actions/setup-nix/action.yml b/.github/actions/setup-nix/action.yml
new file mode 100644
index 0000000..dc759fe
--- /dev/null
+++ b/.github/actions/setup-nix/action.yml
@@ -0,0 +1,39 @@
+name: Setup Nix
+description: Install upstream Nix and enable the shared Cachix binary cache.
+inputs:
+  cachix-name:
+    description: Name of the Cachix cache to use.
+    required: false
+    default: opendefensecloud
+  cachix-auth-token:
+    description: >-
+      Cachix auth token. Leave empty to fall back to a read-only cache, which
+      is what happens on fork pull requests, where secrets are unavailable.
+    required: false
+    default: ''
+  cachix-signing-key:
+    description: >-
+      Cachix signing key. Empty disables pushing to the cache.
+    required: false
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Install nix
+      uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+      with:
+        # Use upstream Nix, not the Determinate fork (avoids the
+        # determinate-nixd binary + FlakeHub auto-enablement we don't want).
+        # Upstream announced this option would stop working on 2026-01-01;
+        # nix-installer still honours --prefer-upstream-nix as of 2026-08-31,
+        # but the action always fetches the latest installer, so this is not
+        # pinned. If it ever flips, this is the one place to change.
+        determinate: false
+        # Don't post install telemetry to Determinate Systems.
+        diagnostic-endpoint: ''
+    - name: Use ${{ inputs.cachix-name }} Cachix cache
+      uses: cachix/cachix-action@5f2d7c5294214f71b873db4b969586b980625e71 # v17
+      with:
+        name: ${{ inputs.cachix-name }}
+        authToken: ${{ inputs.cachix-auth-token }}
+        signingKey: ${{ inputs.cachix-signing-key }}
diff --git a/README.md b/README.md
index 6eb0729..333b15e 100644
--- a/README.md
+++ b/README.md
@@ -119,6 +119,45 @@ The repository settings are configurable via make variables (set them in your `M
 | `REPO_STATUS_CHECKS`                   | `[]`    | JSON array of status-check contexts that must pass (e.g. `["CI","Check action pins"]`); each job name is used as-is, so contexts with spaces work; the `required_status_checks` rule is only added when this is non-empty |
 | `REPO_RULESET_BRANCHES`                | `[]`    | JSON array of additional branch patterns the ruleset applies to (e.g. `["release/*"]`); short names are normalized to `refs/heads/...`; the default branch is always protected                                            |
 
+### GitHub Actions
+
+The repo ships composite actions that consuming repositories reference directly.
+Pin them to a SHA with a version comment, as the action-pin check requires. The
+`<40-char-sha>` placeholders below are not copy-pasteable — substitute real digests:
+
+| Action                                | Description                                                    |
+| ---                                   | ---                                                            |
+| `.github/actions/setup-nix`           | Install upstream Nix and enable the shared Cachix cache        |
+| `.github/actions/get-go-version`      | Extract the Go version from `flake.nix`                        |
+| `.github/actions/diff-check`          | Fail if a command left uncommitted changes behind              |
+
+`setup-nix` replaces the two-step Nix installer + Cachix preamble that every
+job needs before it can use `nix develop` as its shell. Secrets are not visible
+inside a composite action, so the caller passes them in:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        shell: nix develop --command bash -e {0}
+    steps:
+      - uses: actions/checkout@<40-char-sha> # v7
+      - name: Set up nix
+        uses: opendefensecloud/dev-kit/.github/actions/setup-nix@<40-char-sha> # v2.1.0
+        with:
+          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
+          cachix-signing-key: ${{ secrets.CACHIX_SIGNING_KEY }}
+      - run: make test
+```
+
+| Input                | Default            | Description                                                              |
+| ---                  | ---                | ---                                                                      |
+| `cachix-name`        | `opendefensecloud` | Cachix cache to use                                                      |
+| `cachix-auth-token`  | `''`               | Auth token; empty falls back to a read-only cache, as on fork PRs        |
+| `cachix-signing-key` | `''`               | Signing key; empty disables pushing to the cache                         |
+
 ### Default git hooks
 
 The dev shell installs the following git hooks automatically: